{"info":{"title":"BIRP public API","version":"1.0.0","description":"Read and write access to the data of one company in BIRP, for shops, connectors and integrations. Server to server: browsers get no CORS headers.\n\nAuthentication: an API key created by the company administrator in BIRP settings, sent as \"Authorization: Bearer $BIRP_API_KEY\". The key decides the company; no request can choose another one.\n\nLists are ordered by id and paginated with a cursor: pass meta.next_cursor as cursor until has_more is false. Errors follow RFC 9457 (application/problem+json) with a stable code. Every response carries X-Request-Id; authenticated responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.\n\nWrites take JSON bodies. Money and quantities are decimal strings such as \"12.50\"; JSON numbers are refused. Every POST carries an Idempotency-Key: a retry with the same key gets the stored response for 24 hours. Records of other systems are linked and found by source and external_id. Nothing is deleted through the API, and issued invoices never change."},"paths":{"/v1/me":{"get":{"tags":["Account"],"summary":"Who am I","security":[{"bearerAuth":[]}],"x-scopes":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeItem"},"example":{"data":{"key":{"name":"WooCommerce sync","prefix":"EXAMPLE-PREFIX","scopes":["products:read","stock:read","orders:read"],"expires_at":"2027-10-05T00:00:00.000Z"},"company":{"id":"00000000-0000-4000-8000-000000000001","name":"Brutaria Exemplu SRL","country_code":"MD","base_currency":"MDL"},"rate_limits":{"window_seconds":60,"per_key_per_minute":600,"per_company_per_minute":1200}}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/me","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[],"description":"The company and key behind the request, and the rate limits that apply. Any valid key, no scope required.","operationId":"getMe"}},"/v1/orders":{"get":{"tags":["Orders"],"summary":"List orders","security":[{"bearerAuth":[]}],"x-scopes":["orders:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPage"},"example":{"data":[{"id":"00000000-0000-4000-8000-000000000051","lines":[{"sku":"FP-BREAD-500","name":"White bread 500 g","unit":"pcs","quantity":"20","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","description":null,"product_kind":"finished_product"}],"notes":"Deliver before 7:00","total":"64.00","number":"EXAMPLE-ORD-0412","source":"woocommerce","status":"confirmed","contact":{"name":"Claire Exemple","email":"achats@example.com","phone":"+33 0 00 00 00 00"},"currency":"EUR","created_at":"2026-09-27T08:00:03.000Z","ordered_at":"2026-09-27T08:00:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","customer_id":"00000000-0000-4000-8000-000000000031","expected_at":"2026-09-29T06:00:00.000Z","confirmed_at":"2026-09-27T08:05:00.000Z","delivered_at":null,"external_ids":[{"source":"woocommerce","external_id":"order-5512"}],"document_kind":"order","billing_address":null,"shipping_address":{"city":"Paris","name":"Claire Exemple","email":null,"line1":"12 rue des Exemples","line2":null,"phone":"+33 0 00 00 00 00","region":null,"company":"Epicerie Exemple SARL","postal_code":"00000","country_code":"FR"}},{"id":"00000000-0000-4000-8000-000000000052","lines":[{"sku":"FP-BREAD-500","name":"White bread 500 g","unit":"pcs","quantity":"2","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.5000","description":null,"product_kind":"finished_product"}],"notes":null,"total":"7.00","number":"EXAMPLE-ORD-0413","source":"woocommerce","status":"draft","contact":{"name":"Jordan Example","email":"jordan.example@example.org","phone":"+1 000 000 0000"},"currency":"USD","created_at":"2026-09-28T15:20:02.000Z","ordered_at":"2026-09-28T15:20:00.000Z","updated_at":"2026-09-28T15:20:02.000Z","customer_id":"00000000-0000-4000-8000-000000000032","expected_at":null,"confirmed_at":null,"delivered_at":null,"external_ids":[{"source":"woocommerce","external_id":"order-5513"}],"document_kind":"order","billing_address":null,"shipping_address":{"city":"Springfield","name":"Jordan Example","email":"jordan.example@example.org","line1":"100 Example Street","line2":"Apt 4","phone":"+1 000 000 0000","region":"IL","company":null,"postal_code":"00000","country_code":"US"}}],"meta":{"limit":50,"has_more":false,"next_cursor":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"limit","message":"must be between 1 and 200"}],"status":422,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid parameter"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A query parameter is invalid or not supported."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"example":50,"required":false,"description":"Page size, 1 to 200. Default 50."},{"in":"query","name":"cursor","schema":{"type":"string"},"example":"opaque-cursor-example","required":false,"description":"next_cursor of the previous page. Pages are ordered by id."},{"in":"query","name":"updated_since","schema":{"type":"string","format":"date-time"},"example":"2026-09-01T00:00:00Z","required":false,"description":"Only records changed at or after this time: ISO 8601 date and time with an offset or Z."},{"in":"query","name":"external_id","schema":{"type":"string","maxLength":255},"example":"1042","required":false,"description":"Identifier in an external system. Requires source."},{"in":"query","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":false,"description":"External system of external_id, in lowercase. Requires external_id."},{"in":"query","name":"status","schema":{"enum":["draft","confirmed","in_production","ready","prepared","in_delivery","delivered","cancelled","returned"],"type":"string"},"example":"confirmed","required":false,"description":"Order status."},{"in":"query","name":"customer_id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000031","required":false,"description":"Orders of one customer."}],"description":"Customer orders of the company. A quote is listed once it is confirmed, as the order it becomes.","operationId":"listOrders"},"post":{"tags":["Orders"],"summary":"Create an order","security":[{"bearerAuth":[]}],"x-scopes":["orders:write"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000051","lines":[{"sku":"FP-BREAD-500","name":"White bread 500 g","unit":"pcs","quantity":"20","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","description":null,"product_kind":"finished_product"}],"notes":"Deliver before 7:00","total":"64.00","number":"EXAMPLE-ORD-0412","source":"woocommerce","status":"draft","contact":{"name":"Claire Exemple","email":"achats@example.com","phone":"+33 0 00 00 00 00"},"currency":"EUR","created_at":"2026-09-27T08:00:03.000Z","ordered_at":"2026-09-27T08:00:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","customer_id":"00000000-0000-4000-8000-000000000031","expected_at":"2026-09-29T06:00:00.000Z","confirmed_at":null,"delivered_at":null,"external_ids":[{"source":"woocommerce","external_id":"order-5512"}],"document_kind":"order","billing_address":null,"shipping_address":{"city":"Paris","name":"Claire Exemple","email":null,"line1":"12 rue des Exemples","line2":null,"phone":"+33 0 00 00 00 00","region":null,"company":"Epicerie Exemple SARL","postal_code":"00000","country_code":"FR"}}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Created, in draft."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["orders:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"sku_ambiguous":{"value":{"code":"sku_ambiguous","type":"https://birp.io/developers/errors/sku_ambiguous","title":"SKU matches two products","detail":"The SKU matches a goods item and a finished product. Add kind to the reference.","errors":[{"field":"lines[0].product","message":"matches a goods item and a finished product; add kind"}],"status":409,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"SKU of two products"},"external_id_conflict":{"value":{"code":"external_id_conflict","type":"https://birp.io/developers/errors/external_id_conflict","title":"External id in use","detail":"This external id of this source already identifies another record of the company.","errors":[{"field":"external_id","message":"already identifies another record of the company for this source"}],"status":409,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Order already imported"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"reference_not_found":{"value":{"code":"reference_not_found","type":"https://birp.io/developers/errors/reference_not_found","title":"Reference not found","detail":"A reference in the request matches no record of the company.","errors":[{"field":"lines[0].product","message":"matches no record of the company"}],"status":422,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown product"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/orders","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Creates a customer order in draft, numbered by the company numbering. Lines name finished products by id, external id or SKU, with their unit price; a line whose product is not found fails the whole order. The customer is an existing one, or created or updated with the order (customer_upsert, which needs customers:write too). source with external_id records where the order comes from and prevents importing the same order twice.","operationId":"createOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"},"examples":{"example":{"value":{"lines":[{"product":{"sku":"FP-BREAD-500"},"quantity":"20","unit_price":"3.20"}],"notes":"Deliver before 7:00","source":"woocommerce","currency":"EUR","customer":{"source":"woocommerce","external_id":"cust-77"},"ordered_at":"2026-09-27T08:00:00Z","expected_at":"2026-09-29T06:00:00Z","external_id":"order-5512","shipping_address":{"city":"Paris","name":"Claire Exemple","email":null,"line1":"12 rue des Exemples","line2":null,"phone":"+33 0 00 00 00 00","region":null,"company":"Epicerie Exemple SARL","postal_code":"00000","country_code":"FR"}},"summary":"Example"}}}},"required":true}}},"/v1/invoices":{"get":{"tags":["Invoices"],"summary":"List invoices","security":[{"bearerAuth":[]}],"x-scopes":["invoices:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicePage"},"example":{"data":[{"id":"00000000-0000-4000-8000-000000000061","type":"invoice","buyer":{"city":"Paris","name":"Epicerie Exemple SARL","address":"12 rue des Exemples","country":"France","vat_number":"EXAMPLE-VAT-0002","postal_code":"00000","registration_number":"EXAMPLE-0002"},"lines":[{"id":"00000000-0000-4000-8000-000000000071","unit":"pcs","details":null,"discount":"0.00","position":0,"quantity":"20.0000","vat_rate":"20.00","line_total":"64.00","lot_number":"EXAMPLE-LOT-0001","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","vat_amount":"12.80","description":"White bread 500 g","product_kind":"finished_product"},{"id":"00000000-0000-4000-8000-000000000072","unit":"kg","details":null,"discount":"0.00","position":1,"quantity":"4.0000","vat_rate":"0.00","line_total":"50.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000011","unit_price":"12.5000","vat_amount":"0.00","description":"Wheat flour 25 kg","product_kind":"goods"}],"notes":null,"total":"126.80","due_at":"2026-10-28T00:00:00.000Z","number":"EXAMPLE-INV-0098","seller":{"city":"Chisinau","name":"Brutaria Exemplu SRL","address":"Str. Exemplului 4","country":"Moldova","vat_number":"EXAMPLE-VAT-0001","postal_code":"MD-0000","registration_number":"EXAMPLE-0001"},"status":"issued","paid_at":null,"payment":{"method":"bank_transfer","reference":"EXAMPLE-INV-0098","terms_days":30,"bank_account":"EXAMPLE-IBAN-0001"},"currency":"EUR","order_id":"00000000-0000-4000-8000-000000000051","subtotal":"114.00","issued_at":"2026-09-28T00:00:00.000Z","total_vat":"12.80","amount_due":"66.80","created_at":"2026-09-28T09:12:40.000Z","updated_at":"2026-09-28T14:05:12.417Z","amount_paid":"60.00","customer_id":"00000000-0000-4000-8000-000000000031","supplied_at":"2026-09-28T00:00:00.000Z","external_ids":[],"legal_footer":null,"vat_breakdown":[{"tax_code":"ZERO","vat_rate":"0.00","vat_amount":"0.00","taxable_amount":"50.00"},{"tax_code":"STANDARD","vat_rate":"20.00","vat_amount":"12.80","taxable_amount":"64.00"}],"payment_status":"partially_paid","total_discount":"0.00","related_invoice_id":null,"vat_exemption_text":null,"vat_exemption_reason":null},{"id":"00000000-0000-4000-8000-000000000062","type":"invoice","buyer":{"city":"Chisinau","name":"Panificatie Exemplu SRL","address":"Str. Exemplului 1","country":"Moldova","vat_number":"EXAMPLE-VAT-0003","postal_code":"MD-0000","registration_number":"EXAMPLE-0003"},"lines":[{"id":"00000000-0000-4000-8000-000000000073","unit":"kg","details":null,"discount":"0.00","position":0,"quantity":"100.0000","vat_rate":"20.00","line_total":"1250.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000011","unit_price":"12.5000","vat_amount":"250.00","description":"Wheat flour 25 kg","product_kind":"goods"}],"notes":null,"total":"1500.00","due_at":"2026-10-10T00:00:00.000Z","number":"EXAMPLE-INV-0097","seller":{"city":"Chisinau","name":"Brutaria Exemplu SRL","address":"Str. Exemplului 4","country":"Moldova","vat_number":"EXAMPLE-VAT-0001","postal_code":"MD-0000","registration_number":"EXAMPLE-0001"},"status":"issued","paid_at":"2026-09-30T00:00:00.000Z","payment":{"method":"bank_transfer","reference":"EXAMPLE-INV-0097","terms_days":15,"bank_account":"EXAMPLE-IBAN-0001"},"currency":"MDL","order_id":null,"subtotal":"1250.00","issued_at":"2026-09-25T00:00:00.000Z","total_vat":"250.00","amount_due":"0.00","created_at":"2026-09-25T10:00:00.000Z","updated_at":"2026-09-30T08:00:00.000Z","amount_paid":"1500.00","customer_id":"00000000-0000-4000-8000-000000000033","supplied_at":"2026-09-25T00:00:00.000Z","external_ids":[],"legal_footer":null,"vat_breakdown":[{"tax_code":"STANDARD","vat_rate":"20.00","vat_amount":"250.00","taxable_amount":"1250.00"}],"payment_status":"paid","total_discount":"0.00","related_invoice_id":null,"vat_exemption_text":null,"vat_exemption_reason":null}],"meta":{"limit":50,"has_more":false,"next_cursor":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"limit","message":"must be between 1 and 200"}],"status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid parameter"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A query parameter is invalid or not supported."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"example":50,"required":false,"description":"Page size, 1 to 200. Default 50."},{"in":"query","name":"cursor","schema":{"type":"string"},"example":"opaque-cursor-example","required":false,"description":"next_cursor of the previous page. Pages are ordered by id."},{"in":"query","name":"updated_since","schema":{"type":"string","format":"date-time"},"example":"2026-09-01T00:00:00Z","required":false,"description":"Only records changed at or after this time: ISO 8601 date and time with an offset or Z."},{"in":"query","name":"external_id","schema":{"type":"string","maxLength":255},"example":"1042","required":false,"description":"Identifier in an external system. Requires source."},{"in":"query","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":false,"description":"External system of external_id, in lowercase. Requires external_id."},{"in":"query","name":"status","schema":{"enum":["draft","issued","sent","partially_paid","paid","overdue","cancelled","refunded"],"type":"string"},"example":"issued","required":false,"description":"Document status."},{"in":"query","name":"customer_id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000031","required":false,"description":"Invoices of one customer."}],"description":"Invoices, credit notes and proformas of the company, with their lines, VAT totals per rate and payment status. Recording, confirming or deleting a payment counts as a change for updated_since.","operationId":"listInvoices"},"post":{"tags":["Invoices"],"summary":"Create a draft invoice","security":[{"bearerAuth":[]}],"x-scopes":["invoices:write"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000061","type":"invoice","buyer":{"city":"Paris","name":"Epicerie Exemple SARL","address":"12 rue des Exemples","country":"France","vat_number":"EXAMPLE-VAT-0002","postal_code":"00000","registration_number":"EXAMPLE-0002"},"lines":[{"id":"00000000-0000-4000-8000-000000000071","unit":"pcs","details":null,"discount":"0.00","position":0,"quantity":"20.0000","vat_rate":"20.00","line_total":"64.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","vat_amount":"12.80","description":"White bread 500 g","product_kind":"finished_product"},{"id":"00000000-0000-4000-8000-000000000072","unit":"kg","details":null,"discount":"0.00","position":1,"quantity":"4.0000","vat_rate":"0.00","line_total":"50.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000011","unit_price":"12.5000","vat_amount":"0.00","description":"Wheat flour 25 kg","product_kind":"goods"}],"notes":null,"total":"126.80","due_at":null,"number":null,"seller":{"city":"Chisinau","name":"Brutaria Exemplu SRL","address":"Str. Exemplului 4","country":"Moldova","vat_number":"EXAMPLE-VAT-0001","postal_code":"MD-0000","registration_number":"EXAMPLE-0001"},"status":"draft","paid_at":null,"payment":{"method":"bank_transfer","reference":null,"terms_days":30,"bank_account":"EXAMPLE-IBAN-0001"},"currency":"EUR","order_id":"00000000-0000-4000-8000-000000000051","subtotal":"114.00","issued_at":"2026-09-28T00:00:00.000Z","total_vat":"12.80","amount_due":"126.80","created_at":"2026-09-28T09:12:40.000Z","updated_at":"2026-09-28T14:05:12.417Z","amount_paid":"0.00","customer_id":"00000000-0000-4000-8000-000000000031","supplied_at":"2026-09-28T00:00:00.000Z","external_ids":[],"legal_footer":null,"vat_breakdown":[{"tax_code":"ZERO","vat_rate":"0.00","vat_amount":"0.00","taxable_amount":"50.00"},{"tax_code":"STANDARD","vat_rate":"20.00","vat_amount":"12.80","taxable_amount":"64.00"}],"payment_status":"unpaid","total_discount":"0.00","related_invoice_id":null,"vat_exemption_text":null,"vat_exemption_reason":null}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Created, in draft."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["invoices:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"no_rule_for_date":{"value":{"code":"no_rule_for_date","date":"2026-09-28","type":"https://birp.io/developers/errors/no_rule_for_date","title":"No tax rule for the date","detail":"No tax rule of the company exists for this tax code at the document date.","errors":[{"field":"lines[0].tax_code","message":"has no tax rule of the company at the document date"}],"status":422,"instance":"/v1/invoices","tax_code":"STANDARD","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No rule for the code at the date"},"tax_code_mismatch":{"value":{"code":"tax_code_mismatch","type":"https://birp.io/developers/errors/tax_code_mismatch","title":"Tax code mismatch","detail":"With this rate and the VAT exemption reason of the invoice, the line would be recorded under another tax code.","errors":[{"field":"lines[1].tax_code","message":"would be recorded under another tax code; set vat_exemption_reason to match the code"}],"status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Code needs another exemption reason"},"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"reference_not_found":{"value":{"code":"reference_not_found","type":"https://birp.io/developers/errors/reference_not_found","title":"Reference not found","detail":"A reference in the request matches no record of the company.","errors":[{"field":"customer","message":"matches no record of the company"}],"status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown customer"},"tax_rules_unavailable":{"value":{"code":"tax_rules_unavailable","date":"2026-09-28","type":"https://birp.io/developers/errors/tax_rules_unavailable","title":"Tax rules unavailable","detail":"No tax rules of the company's country apply at this date, so no tax can be computed.","status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No tax rules at the date"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"},"company_profile_incomplete":{"value":{"code":"company_profile_incomplete","type":"https://birp.io/developers/errors/company_profile_incomplete","title":"Company profile incomplete","detail":"The company profile lacks seller details an invoice requires. A company administrator can complete them in BIRP settings.","status":422,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","missing_fields":["address","postal_code"]},"summary":"Seller details missing"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/invoices","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Creates an invoice in draft. BIRP computes each line total (quantity times unit price, rounded half up to the cent), the VAT of each line from the tax rule of its tax_code at the document date, and the totals; totals, VAT amounts and rates cannot be sent. The seller details come from the company profile, the buyer details from the customer. The draft has no number until it is issued.","operationId":"createInvoice","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"},"examples":{"example":{"value":{"lines":[{"product":{"sku":"FP-BREAD-500"},"quantity":"20","tax_code":"STANDARD","unit_price":"3.20"},{"product":{"sku":"SP-FLOUR-25"},"quantity":"4","tax_code":"ZERO","unit_price":"12.50"}],"order":{"id":"00000000-0000-4000-8000-000000000051"},"currency":"EUR","customer":{"id":"00000000-0000-4000-8000-000000000031"},"issue_date":"2026-09-28","payment_terms_days":30},"summary":"Example"}}}},"required":true}}},"/v1/products":{"get":{"tags":["Products"],"summary":"List products","security":[{"bearerAuth":[]}],"x-scopes":["products:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPage"},"example":{"data":[{"id":"00000000-0000-4000-8000-000000000011","sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","status":"active","barcode":"2000000000015","currency":"MDL","image_url":null,"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"category_id":"00000000-0000-4000-8000-000000000021","external_ids":[{"source":"woocommerce","external_id":"1042"}]},{"id":"00000000-0000-4000-8000-000000000012","sku":"FP-BREAD-500","kind":"finished_product","name":"White bread 500 g","unit":"pcs","price":"3.20","status":"active","barcode":"2000000000022","currency":"EUR","image_url":"https://files.example.com/temporary/white-bread.png","created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"category_id":"00000000-0000-4000-8000-000000000022","external_ids":[]}],"meta":{"limit":50,"has_more":true,"next_cursor":"opaque-cursor-example"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"limit","message":"must be between 1 and 200"}],"status":422,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid parameter"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A query parameter is invalid or not supported."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"example":50,"required":false,"description":"Page size, 1 to 200. Default 50."},{"in":"query","name":"cursor","schema":{"type":"string"},"example":"opaque-cursor-example","required":false,"description":"next_cursor of the previous page. Pages are ordered by id."},{"in":"query","name":"updated_since","schema":{"type":"string","format":"date-time"},"example":"2026-09-01T00:00:00Z","required":false,"description":"Only records changed at or after this time: ISO 8601 date and time with an offset or Z."},{"in":"query","name":"external_id","schema":{"type":"string","maxLength":255},"example":"1042","required":false,"description":"Identifier in an external system. Requires source."},{"in":"query","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":false,"description":"External system of external_id, in lowercase. Requires external_id."},{"in":"query","name":"sku","schema":{"type":"string"},"example":"SP-FLOUR-25","required":false,"description":"Exact product reference. May match one goods item and one finished product."},{"in":"query","name":"barcode","schema":{"type":"string"},"example":"2000000000015","required":false,"description":"Exact barcode."},{"in":"query","name":"status","schema":{"enum":["active","archived"],"type":"string"},"example":"active","required":false,"description":"active or archived."},{"in":"query","name":"kind","schema":{"enum":["goods","finished_product"],"type":"string"},"example":"goods","required":false,"description":"goods or finished_product."}],"description":"Resale goods and finished products of the company, in one list ordered by id. Archived products are included unless status filters them out.","operationId":"listProducts"},"post":{"tags":["Products"],"summary":"Create a product","security":[{"bearerAuth":[]}],"x-scopes":["products:write"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000011","sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","status":"active","barcode":"2000000000015","currency":"MDL","image_url":null,"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"category_id":"00000000-0000-4000-8000-000000000021","external_ids":[{"source":"woocommerce","external_id":"1042"}]}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Created."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"sku_taken":{"value":{"code":"sku_taken","type":"https://birp.io/developers/errors/sku_taken","title":"SKU in use","detail":"Another product of the company already has this SKU.","errors":[{"field":"sku","message":"is used by another product of the company"}],"status":409,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"SKU used by another product"},"barcode_taken":{"value":{"code":"barcode_taken","type":"https://birp.io/developers/errors/barcode_taken","title":"Barcode in use","detail":"Another product of the company already has this barcode.","errors":[{"field":"barcode","message":"is used by another product of the company"}],"status":409,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Barcode used by another product"},"external_id_conflict":{"value":{"code":"external_id_conflict","type":"https://birp.io/developers/errors/external_id_conflict","title":"External id in use","detail":"This external id of this source already identifies another record of the company.","errors":[{"field":"external_ids[0]","message":"already identifies another record of the company for this source"}],"status":409,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"External id used by another product"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"reference_not_found":{"value":{"code":"reference_not_found","type":"https://birp.io/developers/errors/reference_not_found","title":"Reference not found","detail":"A reference in the request matches no record of the company.","errors":[{"field":"category","message":"matches no record of the company"}],"status":422,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown category"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Creates a goods item (bought and resold) or a finished product (made by the company). A SKU that another product of the company already has, of either kind, is refused; when left out, the company numbering generates one. The product and its external ids are created together, or not at all.","operationId":"createProduct","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreate"},"examples":{"example":{"value":{"sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","barcode":"2000000000015","category":{"id":"00000000-0000-4000-8000-000000000021"},"currency":"MDL","external_ids":[{"source":"woocommerce","external_id":"1042"}]},"summary":"Example"}}}},"required":true}}},"/v1/customers":{"get":{"tags":["Customers"],"summary":"List customers","security":[{"bearerAuth":[]}],"x-scopes":["customers:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerPage"},"example":{"data":[{"id":"00000000-0000-4000-8000-000000000031","name":"Epicerie Exemple SARL","email":"achats@example.com","phone":"+33 0 00 00 00 00","address":{"city":"Paris","line1":"12 rue des Exemples","line2":null,"country":"France","postal_code":"00000"},"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","vat_number":"EXAMPLE-VAT-0002","contact_name":"Claire Exemple","country_code":"FR","external_ids":[{"source":"woocommerce","external_id":"cust-77"}],"customer_type":"b2b","registration_number":"EXAMPLE-0002"},{"id":"00000000-0000-4000-8000-000000000032","name":"Jordan Example","email":"jordan.example@example.org","phone":"+1 000 000 0000","address":{"city":"Springfield","line1":"100 Example Street","line2":"Apt 4","country":"United States","postal_code":"00000"},"created_at":"2026-09-28T15:20:01.000Z","updated_at":"2026-09-28T15:20:01.000Z","vat_number":null,"contact_name":null,"country_code":"US","external_ids":[{"source":"woocommerce","external_id":"cust-78"}],"customer_type":"b2c","registration_number":null},{"id":"00000000-0000-4000-8000-000000000033","name":"Panificatie Exemplu SRL","email":"comenzi@example.com","phone":"+373 00 000 000","address":{"city":"Chisinau","line1":"Str. Exemplului 1","line2":null,"country":"Moldova","postal_code":"MD-0000"},"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","vat_number":"EXAMPLE-VAT-0003","contact_name":"Ana Exemplu","country_code":"MD","external_ids":[],"customer_type":"b2b","registration_number":"EXAMPLE-0003"}],"meta":{"limit":50,"has_more":false,"next_cursor":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"limit","message":"must be between 1 and 200"}],"status":422,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid parameter"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A query parameter is invalid or not supported."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"example":50,"required":false,"description":"Page size, 1 to 200. Default 50."},{"in":"query","name":"cursor","schema":{"type":"string"},"example":"opaque-cursor-example","required":false,"description":"next_cursor of the previous page. Pages are ordered by id."},{"in":"query","name":"updated_since","schema":{"type":"string","format":"date-time"},"example":"2026-09-01T00:00:00Z","required":false,"description":"Only records changed at or after this time: ISO 8601 date and time with an offset or Z."},{"in":"query","name":"external_id","schema":{"type":"string","maxLength":255},"example":"1042","required":false,"description":"Identifier in an external system. Requires source."},{"in":"query","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":false,"description":"External system of external_id, in lowercase. Requires external_id."},{"in":"query","name":"email","schema":{"type":"string"},"example":"achats@example.com","required":false,"description":"Contact email, case-insensitive exact match."},{"in":"query","name":"tax_id","schema":{"type":"string"},"example":"EXAMPLE-0002","required":false,"description":"Registration number, exact match, surrounding spaces ignored."}],"description":"Customers of the company. Emails are not unique: the email filter can return several customers.","operationId":"listCustomers"},"post":{"tags":["Customers"],"summary":"Create a customer","security":[{"bearerAuth":[]}],"x-scopes":["customers:write"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000031","name":"Epicerie Exemple SARL","email":"achats@example.com","phone":"+33 0 00 00 00 00","address":{"city":"Paris","line1":"12 rue des Exemples","line2":null,"country":"France","postal_code":"00000"},"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","vat_number":"EXAMPLE-VAT-0002","contact_name":"Claire Exemple","country_code":"FR","external_ids":[{"source":"woocommerce","external_id":"cust-77"}],"customer_type":"b2b","registration_number":"EXAMPLE-0002"}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Created."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["customers:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"external_id_conflict":{"value":{"code":"external_id_conflict","type":"https://birp.io/developers/errors/external_id_conflict","title":"External id in use","detail":"This external id of this source already identifies another record of the company.","errors":[{"field":"external_ids[0]","message":"already identifies another record of the company for this source"}],"status":409,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"External id used by another customer"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/customers","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Creates a customer. Customers are not deduplicated on create; to find an existing one first, use the upsert by external id with match_by.","operationId":"createCustomer","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCreate"},"examples":{"example":{"value":{"name":"Epicerie Exemple SARL","email":"achats@example.com","phone":"+33 0 00 00 00 00","address":{"city":"Paris","line1":"12 rue des Exemples","line2":null,"country":"France","postal_code":"00000"},"vat_number":"EXAMPLE-VAT-0002","contact_name":"Claire Exemple","country_code":"FR","external_ids":[{"source":"woocommerce","external_id":"cust-77"}],"customer_type":"b2b","registration_number":"EXAMPLE-0002"},"summary":"Example"}}}},"required":true}}},"/v1/tax-codes":{"get":{"tags":["Invoices"],"summary":"List tax codes","security":[{"bearerAuth":[]}],"x-scopes":["invoices:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxCodeList"},"example":{"data":[{"code":"STANDARD","rate":"20.0000","label":"Tax code, article on the standard rate","effective_to":null,"effective_from":"2015-01-01"},{"code":"ZERO","rate":"0.0000","label":"Tax code, article on zero-rated supplies","effective_to":null,"effective_from":"2015-01-01"}],"date":"2026-10-05"}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["invoices:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"date","message":"must be a calendar date, YYYY-MM-DD"}],"status":422,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid date"},"tax_rules_unavailable":{"value":{"code":"tax_rules_unavailable","date":"2026-10-05","type":"https://birp.io/developers/errors/tax_rules_unavailable","title":"Tax rules unavailable","detail":"No tax rules of the company's country apply at this date, so no tax can be computed.","status":422,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No tax rules at the date"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The date is invalid, or the company has no tax rules at it."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/tax-codes","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"date","schema":{"type":"string","format":"date"},"example":"2026-10-05","required":false,"description":"YYYY-MM-DD. Left out: the company today."}],"description":"The tax codes valid at a date under the rules of the company's country: what to send as tax_code on invoice lines. The codes and their rates depend on those rules. Without date: the company today. Codes in the examples are placeholders.","operationId":"listTaxCodes"}},"/v1/categories":{"get":{"tags":["Categories"],"summary":"List categories","security":[{"bearerAuth":[]}],"x-scopes":["categories:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryPage"},"example":{"data":[{"id":"00000000-0000-4000-8000-000000000021","name":"Flour","created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","description":"Flours for resale","external_ids":[],"product_kind":"goods"}],"meta":{"limit":50,"has_more":false,"next_cursor":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"limit","message":"must be between 1 and 200"}],"status":422,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid parameter"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A query parameter is invalid or not supported."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"example":50,"required":false,"description":"Page size, 1 to 200. Default 50."},{"in":"query","name":"cursor","schema":{"type":"string"},"example":"opaque-cursor-example","required":false,"description":"next_cursor of the previous page. Pages are ordered by id."},{"in":"query","name":"updated_since","schema":{"type":"string","format":"date-time"},"example":"2026-09-01T00:00:00Z","required":false,"description":"Only records changed at or after this time: ISO 8601 date and time with an offset or Z."},{"in":"query","name":"external_id","schema":{"type":"string","maxLength":255},"example":"1042","required":false,"description":"Identifier in an external system. Requires source."},{"in":"query","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":false,"description":"External system of external_id, in lowercase. Requires external_id."}],"description":"Categories of goods and of finished products. Categories are flat: there is no parent.","operationId":"listCategories"},"post":{"tags":["Categories"],"summary":"Create a category","security":[{"bearerAuth":[]}],"x-scopes":["categories:write"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000021","name":"Flour","created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","description":"Flours for resale","external_ids":[],"product_kind":"goods"}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Created."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["categories:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"category_name_taken":{"value":{"code":"category_name_taken","type":"https://birp.io/developers/errors/category_name_taken","title":"Category name in use","detail":"A category of the same kind already has this name.","errors":[{"field":"name","message":"is used by another category of the same kind"}],"status":409,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Name used in this kind"},"external_id_conflict":{"value":{"code":"external_id_conflict","type":"https://birp.io/developers/errors/external_id_conflict","title":"External id in use","detail":"This external id of this source already identifies another record of the company.","status":409,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"External id used by another category"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/categories","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Creates a category of goods or of finished products. The name is unique per kind in the company.","operationId":"createCategory","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryCreate"},"examples":{"example":{"value":{"name":"Flour","description":"Flours for resale","product_kind":"goods"},"summary":"Example"}}}},"required":true}}},"/v1/warehouses":{"get":{"tags":["Stock"],"summary":"List warehouses","security":[{"bearerAuth":[]}],"x-scopes":["stock:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehousePage"},"example":{"data":[{"id":"00000000-0000-4000-8000-000000000041","kind":"warehouse","name":"Main warehouse","status":"active","address":"Str. Exemplului 4, Chisinau","created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"external_ids":[]}],"meta":{"limit":50,"has_more":false,"next_cursor":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"limit","message":"must be between 1 and 200"}],"status":422,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid parameter"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A query parameter is invalid or not supported."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/warehouses","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"example":50,"required":false,"description":"Page size, 1 to 200. Default 50."},{"in":"query","name":"cursor","schema":{"type":"string"},"example":"opaque-cursor-example","required":false,"description":"next_cursor of the previous page. Pages are ordered by id."},{"in":"query","name":"updated_since","schema":{"type":"string","format":"date-time"},"example":"2026-09-01T00:00:00Z","required":false,"description":"Only records changed at or after this time: ISO 8601 date and time with an offset or Z."},{"in":"query","name":"external_id","schema":{"type":"string","maxLength":255},"example":"1042","required":false,"description":"Identifier in an external system. Requires source."},{"in":"query","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":false,"description":"External system of external_id, in lowercase. Requires external_id."}],"description":"Warehouses of the company, shop warehouses included, archived ones included.","operationId":"listWarehouses"}},"/v1/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get an order","security":[{"bearerAuth":[]}],"x-scopes":["orders:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000051","lines":[{"sku":"FP-BREAD-500","name":"White bread 500 g","unit":"pcs","quantity":"20","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","description":null,"product_kind":"finished_product"}],"notes":"Deliver before 7:00","total":"64.00","number":"EXAMPLE-ORD-0412","source":"woocommerce","status":"confirmed","contact":{"name":"Claire Exemple","email":"achats@example.com","phone":"+33 0 00 00 00 00"},"currency":"EUR","created_at":"2026-09-27T08:00:03.000Z","ordered_at":"2026-09-27T08:00:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","customer_id":"00000000-0000-4000-8000-000000000031","expected_at":"2026-09-29T06:00:00.000Z","confirmed_at":"2026-09-27T08:05:00.000Z","delivered_at":null,"external_ids":[{"source":"woocommerce","external_id":"order-5512"}],"document_kind":"order","billing_address":null,"shipping_address":{"city":"Paris","name":"Claire Exemple","email":null,"line1":"12 rue des Exemples","line2":null,"phone":"+33 0 00 00 00 00","region":null,"company":"Epicerie Exemple SARL","postal_code":"00000","country_code":"FR"}}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000051","required":true,"description":"Order identifier."}],"description":"One customer order of the company.","operationId":"getOrder"},"patch":{"tags":["Orders"],"summary":"Update a draft order","security":[{"bearerAuth":[]}],"x-scopes":["orders:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000051","lines":[{"sku":"FP-BREAD-500","name":"White bread 500 g","unit":"pcs","quantity":"20","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","description":null,"product_kind":"finished_product"}],"notes":"Deliver before 7:00","total":"64.00","number":"EXAMPLE-ORD-0412","source":"woocommerce","status":"draft","contact":{"name":"Claire Exemple","email":"achats@example.com","phone":"+33 0 00 00 00 00"},"currency":"EUR","created_at":"2026-09-27T08:00:03.000Z","ordered_at":"2026-09-27T08:00:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","customer_id":"00000000-0000-4000-8000-000000000031","expected_at":"2026-09-29T06:00:00.000Z","confirmed_at":null,"delivered_at":null,"external_ids":[{"source":"woocommerce","external_id":"order-5512"}],"document_kind":"order","billing_address":null,"shipping_address":{"city":"Paris","name":"Claire Exemple","email":null,"line1":"12 rue des Exemples","line2":null,"phone":"+33 0 00 00 00 00","region":null,"company":"Epicerie Exemple SARL","postal_code":"00000","country_code":"FR"}}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Updated."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["orders:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"},"invalid_status_transition":{"value":{"code":"invalid_status_transition","type":"https://birp.io/developers/errors/invalid_status_transition","title":"Status does not allow this","detail":"The current status of the record does not allow this action or change.","status":409,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","allowed_from":["draft"],"current_status":"confirmed"},"summary":"Not a draft any more"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000051","required":true,"description":"Order identifier."}],"description":"Changes a draft order: lines (replaced as a whole, total recomputed), currency, addresses, expected date, notes. Once confirmed, an order can no longer be changed through the API.","operationId":"updateOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderUpdate"},"examples":{"example":{"value":{"notes":"Deliver before 7:00","expected_at":"2026-09-29T06:00:00Z"},"summary":"Example"}}}},"required":true}}},"/v1/openapi.json":{"get":{"tags":["Account"],"summary":"OpenAPI document","x-scopes":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"},"example":{"info":{"title":"BIRP public API","version":"1.0.0"},"openapi":"3.1.0","servers":[{"url":"https://api.birp.io"}]}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request."}},"description":"The OpenAPI 3.1 document of the API."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/openapi.json","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"ip"},"summary":"Client IP limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The rate limit of the client IP was reached."}},"parameters":[],"description":"This document. Public: no key is needed, and browsers may read it from any origin.","operationId":"getOpenApi"}},"/v1/stock/levels":{"get":{"tags":["Stock"],"summary":"List stock levels","security":[{"bearerAuth":[]}],"x-scopes":["stock:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLevelPage"},"example":{"data":[{"id":"EXAMPLE-LEVEL-0001","unit":"kg","quantity":"12.5","lot_count":2,"product_id":"00000000-0000-4000-8000-000000000011","product_kind":"goods","warehouse_id":"00000000-0000-4000-8000-000000000041"},{"id":"EXAMPLE-LEVEL-0002","unit":"pcs","quantity":"30","lot_count":1,"product_id":"00000000-0000-4000-8000-000000000012","product_kind":"finished_product","warehouse_id":null}],"meta":{"limit":50,"has_more":false,"next_cursor":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"limit","message":"must be between 1 and 200"}],"status":422,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid parameter"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A query parameter is invalid or not supported."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/stock/levels","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"example":50,"required":false,"description":"Page size, 1 to 200. Default 50."},{"in":"query","name":"cursor","schema":{"type":"string"},"example":"opaque-cursor-example","required":false,"description":"next_cursor of the previous page. Pages are ordered by id."},{"in":"query","name":"warehouse_id","schema":{"type":"string"},"example":"00000000-0000-4000-8000-000000000041","required":false,"description":"A warehouse id, or none for stock not assigned to a warehouse."},{"in":"query","name":"product_id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000011","required":false,"description":"One product."}],"description":"Physical stock, one row per product, warehouse and unit. Archived products are left out, and reserved quantities are not deducted. Stock held in shops is not reported per shop. Stock levels take no updated_since: read them per warehouse or per product.","operationId":"listStockLevels"}},"/v1/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Get an invoice","security":[{"bearerAuth":[]}],"x-scopes":["invoices:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000061","type":"invoice","buyer":{"city":"Paris","name":"Epicerie Exemple SARL","address":"12 rue des Exemples","country":"France","vat_number":"EXAMPLE-VAT-0002","postal_code":"00000","registration_number":"EXAMPLE-0002"},"lines":[{"id":"00000000-0000-4000-8000-000000000071","unit":"pcs","details":null,"discount":"0.00","position":0,"quantity":"20.0000","vat_rate":"20.00","line_total":"64.00","lot_number":"EXAMPLE-LOT-0001","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","vat_amount":"12.80","description":"White bread 500 g","product_kind":"finished_product"},{"id":"00000000-0000-4000-8000-000000000072","unit":"kg","details":null,"discount":"0.00","position":1,"quantity":"4.0000","vat_rate":"0.00","line_total":"50.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000011","unit_price":"12.5000","vat_amount":"0.00","description":"Wheat flour 25 kg","product_kind":"goods"}],"notes":null,"total":"126.80","due_at":"2026-10-28T00:00:00.000Z","number":"EXAMPLE-INV-0098","seller":{"city":"Chisinau","name":"Brutaria Exemplu SRL","address":"Str. Exemplului 4","country":"Moldova","vat_number":"EXAMPLE-VAT-0001","postal_code":"MD-0000","registration_number":"EXAMPLE-0001"},"status":"issued","paid_at":null,"payment":{"method":"bank_transfer","reference":"EXAMPLE-INV-0098","terms_days":30,"bank_account":"EXAMPLE-IBAN-0001"},"currency":"EUR","order_id":"00000000-0000-4000-8000-000000000051","subtotal":"114.00","issued_at":"2026-09-28T00:00:00.000Z","total_vat":"12.80","amount_due":"66.80","created_at":"2026-09-28T09:12:40.000Z","updated_at":"2026-09-28T14:05:12.417Z","amount_paid":"60.00","customer_id":"00000000-0000-4000-8000-000000000031","supplied_at":"2026-09-28T00:00:00.000Z","external_ids":[],"legal_footer":null,"vat_breakdown":[{"tax_code":"ZERO","vat_rate":"0.00","vat_amount":"0.00","taxable_amount":"50.00"},{"tax_code":"STANDARD","vat_rate":"20.00","vat_amount":"12.80","taxable_amount":"64.00"}],"payment_status":"partially_paid","total_discount":"0.00","related_invoice_id":null,"vat_exemption_text":null,"vat_exemption_reason":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000061","required":true,"description":"Invoice identifier."}],"description":"One invoice, credit note or proforma of the company.","operationId":"getInvoice"},"patch":{"tags":["Invoices"],"summary":"Update a draft invoice","security":[{"bearerAuth":[]}],"x-scopes":["invoices:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000061","type":"invoice","buyer":{"city":"Paris","name":"Epicerie Exemple SARL","address":"12 rue des Exemples","country":"France","vat_number":"EXAMPLE-VAT-0002","postal_code":"00000","registration_number":"EXAMPLE-0002"},"lines":[{"id":"00000000-0000-4000-8000-000000000071","unit":"pcs","details":null,"discount":"0.00","position":0,"quantity":"20.0000","vat_rate":"20.00","line_total":"64.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","vat_amount":"12.80","description":"White bread 500 g","product_kind":"finished_product"},{"id":"00000000-0000-4000-8000-000000000072","unit":"kg","details":null,"discount":"0.00","position":1,"quantity":"4.0000","vat_rate":"0.00","line_total":"50.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000011","unit_price":"12.5000","vat_amount":"0.00","description":"Wheat flour 25 kg","product_kind":"goods"}],"notes":null,"total":"126.80","due_at":null,"number":null,"seller":{"city":"Chisinau","name":"Brutaria Exemplu SRL","address":"Str. Exemplului 4","country":"Moldova","vat_number":"EXAMPLE-VAT-0001","postal_code":"MD-0000","registration_number":"EXAMPLE-0001"},"status":"draft","paid_at":null,"payment":{"method":"bank_transfer","reference":null,"terms_days":30,"bank_account":"EXAMPLE-IBAN-0001"},"currency":"EUR","order_id":"00000000-0000-4000-8000-000000000051","subtotal":"114.00","issued_at":"2026-09-28T00:00:00.000Z","total_vat":"12.80","amount_due":"126.80","created_at":"2026-09-28T09:12:40.000Z","updated_at":"2026-09-28T14:05:12.417Z","amount_paid":"0.00","customer_id":"00000000-0000-4000-8000-000000000031","supplied_at":"2026-09-28T00:00:00.000Z","external_ids":[],"legal_footer":null,"vat_breakdown":[{"tax_code":"ZERO","vat_rate":"0.00","vat_amount":"0.00","taxable_amount":"50.00"},{"tax_code":"STANDARD","vat_rate":"20.00","vat_amount":"12.80","taxable_amount":"64.00"}],"payment_status":"unpaid","total_discount":"0.00","related_invoice_id":null,"vat_exemption_text":null,"vat_exemption_reason":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Updated."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["invoices:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invoice_issued":{"value":{"code":"invoice_issued","type":"https://birp.io/developers/errors/invoice_issued","title":"Invoice already issued","detail":"An issued invoice cannot be changed or issued again. Corrections are made with a credit note.","status":409,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","current_status":"issued"},"summary":"Not a draft"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"no_rule_for_date":{"value":{"code":"no_rule_for_date","date":"2026-09-28","type":"https://birp.io/developers/errors/no_rule_for_date","title":"No tax rule for the date","detail":"No tax rule of the company exists for this tax code at the document date.","errors":[{"field":"lines[0].tax_code","message":"has no tax rule of the company at the document date"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","tax_code":"STANDARD","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No rule for the code at the date"},"tax_code_mismatch":{"value":{"code":"tax_code_mismatch","type":"https://birp.io/developers/errors/tax_code_mismatch","title":"Tax code mismatch","detail":"With this rate and the VAT exemption reason of the invoice, the line would be recorded under another tax code.","errors":[{"field":"lines[1].tax_code","message":"would be recorded under another tax code; set vat_exemption_reason to match the code"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Code needs another exemption reason"},"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"reference_not_found":{"value":{"code":"reference_not_found","type":"https://birp.io/developers/errors/reference_not_found","title":"Reference not found","detail":"A reference in the request matches no record of the company.","errors":[{"field":"customer","message":"matches no record of the company"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown customer"},"tax_rules_unavailable":{"value":{"code":"tax_rules_unavailable","date":"2026-09-28","type":"https://birp.io/developers/errors/tax_rules_unavailable","title":"Tax rules unavailable","detail":"No tax rules of the company's country apply at this date, so no tax can be computed.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No tax rules at the date"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"company_profile_incomplete":{"value":{"code":"company_profile_incomplete","type":"https://birp.io/developers/errors/company_profile_incomplete","title":"Company profile incomplete","detail":"The company profile lacks seller details an invoice requires. A company administrator can complete them in BIRP settings.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","missing_fields":["address","postal_code"]},"summary":"Seller details missing"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000061","required":true,"description":"Invoice identifier."}],"description":"Changes a draft; totals and VAT are recomputed. An issued invoice answers 409 invoice_issued: corrections are credit notes, made in BIRP.","operationId":"updateInvoice","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUpdate"},"examples":{"example":{"value":{"notes":"Thank you for your order","payment_terms_days":15},"summary":"Example"}}}},"required":true}}},"/v1/products/{id}":{"get":{"tags":["Products"],"summary":"Get a product","security":[{"bearerAuth":[]}],"x-scopes":["products:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000011","sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","status":"active","barcode":"2000000000015","currency":"MDL","image_url":null,"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"category_id":"00000000-0000-4000-8000-000000000021","external_ids":[{"source":"woocommerce","external_id":"1042"}]}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000011","required":true,"description":"Product identifier."}],"description":"One goods item or finished product of the company.","operationId":"getProduct"},"patch":{"tags":["Products"],"summary":"Update a product","security":[{"bearerAuth":[]}],"x-scopes":["products:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000011","sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","status":"active","barcode":"2000000000015","currency":"MDL","image_url":null,"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"category_id":"00000000-0000-4000-8000-000000000021","external_ids":[{"source":"woocommerce","external_id":"1042"}]}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Updated."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"sku_taken":{"value":{"code":"sku_taken","type":"https://birp.io/developers/errors/sku_taken","title":"SKU in use","detail":"Another product of the company already has this SKU.","errors":[{"field":"sku","message":"is used by another product of the company"}],"status":409,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"SKU used by another product"},"barcode_taken":{"value":{"code":"barcode_taken","type":"https://birp.io/developers/errors/barcode_taken","title":"Barcode in use","detail":"Another product of the company already has this barcode.","errors":[{"field":"barcode","message":"is used by another product of the company"}],"status":409,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Barcode used by another product"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"reference_not_found":{"value":{"code":"reference_not_found","type":"https://birp.io/developers/errors/reference_not_found","title":"Reference not found","detail":"A reference in the request matches no record of the company.","errors":[{"field":"category","message":"matches no record of the company"}],"status":422,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown category"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products/00000000-0000-4000-8000-000000000011","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000011","required":true,"description":"Product identifier."}],"description":"Changes the fields sent; fields left out are not touched, null clears a nullable field. status archived or active archives or restores the product. The kind never changes.","operationId":"updateProduct","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdate"},"examples":{"example":{"value":{"price":"12.50","status":"active"},"summary":"Example"}}}},"required":true}}},"/v1/customers/{id}":{"get":{"tags":["Customers"],"summary":"Get a customer","security":[{"bearerAuth":[]}],"x-scopes":["customers:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000031","name":"Epicerie Exemple SARL","email":"achats@example.com","phone":"+33 0 00 00 00 00","address":{"city":"Paris","line1":"12 rue des Exemples","line2":null,"country":"France","postal_code":"00000"},"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","vat_number":"EXAMPLE-VAT-0002","contact_name":"Claire Exemple","country_code":"FR","external_ids":[{"source":"woocommerce","external_id":"cust-77"}],"customer_type":"b2b","registration_number":"EXAMPLE-0002"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000031","required":true,"description":"Customer identifier."}],"description":"One customer of the company.","operationId":"getCustomer"},"patch":{"tags":["Customers"],"summary":"Update a customer","security":[{"bearerAuth":[]}],"x-scopes":["customers:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000031","name":"Epicerie Exemple SARL","email":"achats@example.com","phone":"+33 0 00 00 00 00","address":{"city":"Paris","line1":"12 rue des Exemples","line2":null,"country":"France","postal_code":"00000"},"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","vat_number":"EXAMPLE-VAT-0002","contact_name":"Claire Exemple","country_code":"FR","external_ids":[{"source":"woocommerce","external_id":"cust-77"}],"customer_type":"b2b","registration_number":"EXAMPLE-0002"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Updated."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["customers:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/customers/00000000-0000-4000-8000-000000000031","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000031","required":true,"description":"Customer identifier."}],"description":"Changes the fields sent; fields left out are not touched, null clears a field. Address members are updated one by one.","operationId":"updateCustomer","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpdate"},"examples":{"example":{"value":{"phone":"+33 0 00 00 00 00","address":{"city":"Paris"}},"summary":"Example"}}}},"required":true}}},"/v1/products/batch":{"post":{"tags":["Products"],"summary":"Create or update up to 100 products","security":[{"bearerAuth":[]}],"x-scopes":["products:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResultEnvelope"},"example":{"data":{"results":[{"id":"00000000-0000-4000-8000-000000000011","index":0,"status":"updated"},{"id":"00000000-0000-4000-8000-000000000012","index":1,"status":"updated"},{"index":2,"errors":[{"code":"reference_not_found","field":"match","message":"matches no record of the company"}],"status":"failed"}],"summary":{"failed":1,"created":0,"updated":2}}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Per-item results."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Each item names the product with its own match key (id, external id with source, or SKU) and is created or updated on its own. The whole request is validated first; an invalid shape fails it all. Business errors fail only their item, reported in results. One Idempotency-Key covers the whole batch.","operationId":"batchUpsertProducts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductBatchRequest"},"examples":{"example":{"value":{"items":[{"data":{"sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","currency":"MDL"},"match":{"source":"woocommerce","external_id":"1042"}},{"data":{"kind":"finished_product","name":"White bread 500 g","price":"3.20"},"match":{"sku":"FP-BREAD-500"}},{"data":{"kind":"goods","name":"Rye flour 25 kg"},"match":{"id":"00000000-0000-4000-8000-000000000099"}}]},"summary":"Example"}}}},"required":true}}},"/v1/categories/{id}":{"get":{"tags":["Categories"],"summary":"Get a category","security":[{"bearerAuth":[]}],"x-scopes":["categories:read"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000021","name":"Flour","created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","description":"Flours for resale","external_ids":[],"product_kind":"goods"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Success."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:read"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000021","required":true,"description":"Category identifier."}],"description":"One category of goods or finished products.","operationId":"getCategory"},"patch":{"tags":["Categories"],"summary":"Update a category","security":[{"bearerAuth":[]}],"x-scopes":["categories:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000021","name":"Flour","created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","description":"Flours for resale","external_ids":[],"product_kind":"goods"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Updated."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["categories:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"category_name_taken":{"value":{"code":"category_name_taken","type":"https://birp.io/developers/errors/category_name_taken","title":"Category name in use","detail":"A category of the same kind already has this name.","status":409,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Name used in this kind"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/categories/00000000-0000-4000-8000-000000000021","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000021","required":true,"description":"Category identifier."}],"description":"Changes the name or the description. The kind never changes.","operationId":"updateCategory","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryUpdate"},"examples":{"example":{"value":{"description":"Flours for resale"},"summary":"Example"}}}},"required":true}}},"/v1/customers/batch":{"post":{"tags":["Customers"],"summary":"Create or update up to 100 customers","security":[{"bearerAuth":[]}],"x-scopes":["customers:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResultEnvelope"},"example":{"data":{"results":[{"id":"00000000-0000-4000-8000-000000000031","index":0,"status":"updated"},{"id":"00000000-0000-4000-8000-000000000032","index":1,"status":"created"}],"summary":{"failed":0,"created":1,"updated":1}}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Per-item results."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["customers:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/customers/batch","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Each item names the customer with its own match key (id, or external id with source and optional match_by) and is created or updated on its own. The whole request is validated first. One Idempotency-Key covers the whole batch.","operationId":"batchUpsertCustomers","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerBatchRequest"},"examples":{"example":{"value":{"items":[{"data":{"name":"Epicerie Exemple SARL","email":"achats@example.com","country_code":"FR","customer_type":"b2b"},"match":{"source":"woocommerce","match_by":["email"],"external_id":"cust-77"}},{"data":{"name":"Jordan Example","email":"jordan.example@example.org","country_code":"US","customer_type":"b2c"},"match":{"source":"woocommerce","external_id":"cust-78"}}]},"summary":"Example"}}}},"required":true}}},"/v1/stock/adjustments":{"post":{"tags":["Stock"],"summary":"Adjust the stock of a goods item in a warehouse","security":[{"bearerAuth":[]}],"x-scopes":["stock:write"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockAdjustmentItem"},"example":{"data":{"id":"a1b2c3d4-0000-4000-8000-0000000000aa","note":"Weekly count","unit":"kg","level":{"id":"EXAMPLE-LEVEL-0001","unit":"kg","quantity":"12.5","lot_count":2,"product_id":"00000000-0000-4000-8000-000000000011","product_kind":"goods","warehouse_id":"00000000-0000-4000-8000-000000000041"},"reason":"adjustment","quantity":"-2.500","movements":[{"id":"b2c3d4e5-0000-4000-8000-0000000000bb","type":"adjustment","lot_id":"c3d4e5f6-0000-4000-8000-0000000000cc","quantity":"-2.500"}],"reference":"WC-COUNT-2026-10-05","created_at":"2026-10-05T09:12:44.120Z","product_id":"00000000-0000-4000-8000-000000000011","warehouse_id":"00000000-0000-4000-8000-000000000041"}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Recorded."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["stock:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"sku_ambiguous":{"value":{"code":"sku_ambiguous","type":"https://birp.io/developers/errors/sku_ambiguous","title":"SKU matches two products","detail":"The SKU matches a goods item and a finished product. Add kind to the reference.","errors":[{"field":"product","message":"matches a goods item and a finished product; add kind"}],"status":409,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"SKU of two products"},"insufficient_stock":{"value":{"code":"insufficient_stock","type":"https://birp.io/developers/errors/insufficient_stock","title":"Insufficient stock","detail":"The warehouse does not hold enough stock of the product in this unit.","errors":[{"field":"quantity","message":"exceeds the stock of the warehouse in this unit"}],"status":409,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not enough stock"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"reference_not_found":{"value":{"code":"reference_not_found","type":"https://birp.io/developers/errors/reference_not_found","title":"Reference not found","detail":"A reference in the request matches no record of the company.","errors":[{"field":"warehouse","message":"matches no record of the company"}],"status":422,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown warehouse"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/stock/adjustments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Records a receipt, a correction or a loss of a goods item in one warehouse. The answer carries the movements and the resulting stock level, as GET /v1/stock/levels returns it. Finished products are not adjusted through the API in this version: their stock comes from production.","operationId":"createStockAdjustment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockAdjustmentCreate"},"examples":{"example":{"value":{"note":"Weekly count","reason":"adjustment","product":{"sku":"SP-FLOUR-25"},"quantity":"-2.5","reference":"WC-COUNT-2026-10-05","warehouse":{"id":"00000000-0000-4000-8000-000000000041"}},"summary":"Example"}}}},"required":true}}},"/v1/orders/{id}/cancel":{"post":{"tags":["Orders"],"summary":"Cancel an order","security":[{"bearerAuth":[]}],"x-scopes":["orders:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000051","lines":[{"sku":"FP-BREAD-500","name":"White bread 500 g","unit":"pcs","quantity":"20","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","description":null,"product_kind":"finished_product"}],"notes":"Deliver before 7:00","total":"64.00","number":"EXAMPLE-ORD-0412","source":"woocommerce","status":"cancelled","contact":{"name":"Claire Exemple","email":"achats@example.com","phone":"+33 0 00 00 00 00"},"currency":"EUR","created_at":"2026-09-27T08:00:03.000Z","ordered_at":"2026-09-27T08:00:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","customer_id":"00000000-0000-4000-8000-000000000031","expected_at":"2026-09-29T06:00:00.000Z","confirmed_at":"2026-09-27T08:05:00.000Z","delivered_at":null,"external_ids":[{"source":"woocommerce","external_id":"order-5512"}],"document_kind":"order","billing_address":null,"shipping_address":{"city":"Paris","name":"Claire Exemple","email":null,"line1":"12 rue des Exemples","line2":null,"phone":"+33 0 00 00 00 00","region":null,"company":"Epicerie Exemple SARL","postal_code":"00000","country_code":"FR"}}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Cancelled."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["orders:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"},"invalid_status_transition":{"value":{"code":"invalid_status_transition","type":"https://birp.io/developers/errors/invalid_status_transition","title":"Status does not allow this","detail":"The current status of the record does not allow this action or change.","status":409,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","allowed_from":["draft","confirmed"],"current_status":"in_production"},"summary":"Not allowed in the current status"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/cancel","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000051","required":true,"description":"Order identifier."}],"description":"Cancels an order in draft or confirmed, with a reason kept in its history. An order that has reached production is cancelled by the operators in BIRP, not through the API.","operationId":"cancelOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCancel"},"examples":{"example":{"value":{"reason":"Cancelled by the customer in the shop"},"summary":"Example"}}}},"required":true}}},"/v1/invoices/{id}/issue":{"post":{"tags":["Invoices"],"summary":"Issue a draft invoice","security":[{"bearerAuth":[]}],"x-scopes":["invoices:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000061","type":"invoice","buyer":{"city":"Paris","name":"Epicerie Exemple SARL","address":"12 rue des Exemples","country":"France","vat_number":"EXAMPLE-VAT-0002","postal_code":"00000","registration_number":"EXAMPLE-0002"},"lines":[{"id":"00000000-0000-4000-8000-000000000071","unit":"pcs","details":null,"discount":"0.00","position":0,"quantity":"20.0000","vat_rate":"20.00","line_total":"64.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","vat_amount":"12.80","description":"White bread 500 g","product_kind":"finished_product"},{"id":"00000000-0000-4000-8000-000000000072","unit":"kg","details":null,"discount":"0.00","position":1,"quantity":"4.0000","vat_rate":"0.00","line_total":"50.00","lot_number":null,"product_id":"00000000-0000-4000-8000-000000000011","unit_price":"12.5000","vat_amount":"0.00","description":"Wheat flour 25 kg","product_kind":"goods"}],"notes":null,"total":"126.80","due_at":"2026-10-28T00:00:00.000Z","number":"EXAMPLE-INV-0098","seller":{"city":"Chisinau","name":"Brutaria Exemplu SRL","address":"Str. Exemplului 4","country":"Moldova","vat_number":"EXAMPLE-VAT-0001","postal_code":"MD-0000","registration_number":"EXAMPLE-0001"},"status":"issued","paid_at":null,"payment":{"method":"bank_transfer","reference":null,"terms_days":30,"bank_account":"EXAMPLE-IBAN-0001"},"currency":"EUR","order_id":"00000000-0000-4000-8000-000000000051","subtotal":"114.00","issued_at":"2026-09-28T00:00:00.000Z","total_vat":"12.80","amount_due":"126.80","created_at":"2026-09-28T09:12:40.000Z","updated_at":"2026-09-28T14:05:12.417Z","amount_paid":"0.00","customer_id":"00000000-0000-4000-8000-000000000031","supplied_at":"2026-09-28T00:00:00.000Z","external_ids":[],"legal_footer":null,"vat_breakdown":[{"tax_code":"ZERO","vat_rate":"0.00","vat_amount":"0.00","taxable_amount":"50.00"},{"tax_code":"STANDARD","vat_rate":"20.00","vat_amount":"12.80","taxable_amount":"64.00"}],"payment_status":"unpaid","total_discount":"0.00","related_invoice_id":null,"vat_exemption_text":null,"vat_exemption_reason":null}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Issued."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["invoices:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invoice_issued":{"value":{"code":"invoice_issued","type":"https://birp.io/developers/errors/invoice_issued","title":"Invoice already issued","detail":"An issued invoice cannot be changed or issued again. Corrections are made with a credit note.","status":409,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","current_status":"issued"},"summary":"Not a draft"},"numbering_conflict":{"value":{"code":"numbering_conflict","type":"https://birp.io/developers/errors/numbering_conflict","title":"Numbering busy","detail":"The numbering series was busy. Retry the request.","status":409,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Numbering busy"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"no_rule_for_date":{"value":{"code":"no_rule_for_date","date":"2026-09-28","type":"https://birp.io/developers/errors/no_rule_for_date","title":"No tax rule for the date","detail":"No tax rule of the company exists for this tax code at the document date.","errors":[{"field":"lines[0].tax_code","message":"has no tax rule of the company at the document date"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","tax_code":"STANDARD","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No rule for the code at the date"},"tax_code_mismatch":{"value":{"code":"tax_code_mismatch","type":"https://birp.io/developers/errors/tax_code_mismatch","title":"Tax code mismatch","detail":"With this rate and the VAT exemption reason of the invoice, the line would be recorded under another tax code.","errors":[{"field":"lines[1].tax_code","message":"would be recorded under another tax code; set vat_exemption_reason to match the code"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Code needs another exemption reason"},"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"tax_rules_unavailable":{"value":{"code":"tax_rules_unavailable","date":"2026-09-28","type":"https://birp.io/developers/errors/tax_rules_unavailable","title":"Tax rules unavailable","detail":"No tax rules of the company's country apply at this date, so no tax can be computed.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No tax rules at the date"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"},"company_profile_incomplete":{"value":{"code":"company_profile_incomplete","type":"https://birp.io/developers/errors/company_profile_incomplete","title":"Company profile incomplete","detail":"The company profile lacks seller details an invoice requires. A company administrator can complete them in BIRP settings.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","missing_fields":["address","postal_code"]},"summary":"Seller details missing"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/issue","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000061","required":true,"description":"Invoice identifier."}],"description":"Issues a draft: the VAT is recomputed for the issue date, the seller and buyer details are taken again, and the invoice gets the next number of the company series. From then on it never changes through the API.","operationId":"issueInvoice","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceIssue"},"examples":{"example":{"value":{"issue_date":"2026-09-28"},"summary":"Example"}}}},"required":false}}},"/v1/orders/{id}/confirm":{"post":{"tags":["Orders"],"summary":"Confirm a draft order","security":[{"bearerAuth":[]}],"x-scopes":["orders:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000051","lines":[{"sku":"FP-BREAD-500","name":"White bread 500 g","unit":"pcs","quantity":"20","product_id":"00000000-0000-4000-8000-000000000012","unit_price":"3.2000","description":null,"product_kind":"finished_product"}],"notes":"Deliver before 7:00","total":"64.00","number":"EXAMPLE-ORD-0412","source":"woocommerce","status":"confirmed","contact":{"name":"Claire Exemple","email":"achats@example.com","phone":"+33 0 00 00 00 00"},"currency":"EUR","created_at":"2026-09-27T08:00:03.000Z","ordered_at":"2026-09-27T08:00:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","customer_id":"00000000-0000-4000-8000-000000000031","expected_at":"2026-09-29T06:00:00.000Z","confirmed_at":"2026-09-27T08:05:00.000Z","delivered_at":null,"external_ids":[{"source":"woocommerce","external_id":"order-5512"}],"document_kind":"order","billing_address":null,"shipping_address":{"city":"Paris","name":"Claire Exemple","email":null,"line1":"12 rue des Exemples","line2":null,"phone":"+33 0 00 00 00 00","region":null,"company":"Epicerie Exemple SARL","postal_code":"00000","country_code":"FR"}}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Confirmed."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["orders:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"},"invalid_status_transition":{"value":{"code":"invalid_status_transition","type":"https://birp.io/developers/errors/invalid_status_transition","title":"Status does not allow this","detail":"The current status of the record does not allow this action or change.","status":409,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","allowed_from":["draft"],"current_status":"confirmed"},"summary":"Not allowed in the current status"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/orders/00000000-0000-4000-8000-000000000051/confirm","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000051","required":true,"description":"Order identifier."}],"description":"Moves a draft order to confirmed and records the confirmation time. Allowed only from draft.","operationId":"confirmOrder","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderConfirm"},"examples":{"example":{"value":{},"summary":"Example"}}}},"required":false}}},"/v1/invoices/{id}/payments":{"post":{"tags":["Invoices"],"summary":"Record a payment","security":[{"bearerAuth":[]}],"x-scopes":["invoices:write"],"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicePaymentItem"},"example":{"data":{"id":"d4e5f6a7-0000-4000-8000-0000000000dd","amount":"64.50","method":"card","status":"confirmed","paid_on":"2026-10-07","currency":"EUR","reference":"EXAMPLE-PAY-0042","created_at":"2026-10-07T10:02:11.000Z","invoice_id":"00000000-0000-4000-8000-000000000061"}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Recorded."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["invoices:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invoice_not_issued":{"value":{"code":"invoice_not_issued","type":"https://birp.io/developers/errors/invoice_not_issued","title":"Invoice not issued","detail":"Payments can be recorded only on an issued invoice.","status":409,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","current_status":"draft"},"summary":"Draft invoice"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"},"idempotency_key_missing":{"value":{"code":"idempotency_key_missing","type":"https://birp.io/developers/errors/idempotency_key_missing","title":"Idempotency-Key missing","detail":"POST requests must carry an Idempotency-Key header, unique for each distinct request.","status":422,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Idempotency-Key"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/invoices/00000000-0000-4000-8000-000000000061/payments","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000061","required":true,"description":"Invoice identifier."}],"description":"Records a confirmed payment, in the invoice currency, on an issued invoice. The invoice payment status follows from its payments, and the invoice counts as changed for updated_since.","operationId":"createInvoicePayment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicePaymentCreate"},"examples":{"example":{"value":{"amount":"64.50","method":"card","paid_on":"2026-10-07","reference":"EXAMPLE-PAY-0042"},"summary":"Example"}}}},"required":true}}},"/v1/{resource}/{id}/external-refs/{source}":{"put":{"tags":["External ids"],"summary":"Link a record to its id in an external system","security":[{"bearerAuth":[]}],"x-scopes":["products:write","categories:write","customers:write","stock:write","orders:write","invoices:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRefItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000011","source":"woocommerce","resource":"products","external_id":"1042"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"The external id now set."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:write","categories:write","customers:write","stock:write","orders:write","invoices:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"external_id_conflict":{"value":{"code":"external_id_conflict","type":"https://birp.io/developers/errors/external_id_conflict","title":"External id in use","detail":"This external id of this source already identifies another record of the company.","errors":[{"field":"external_id","message":"already identifies another record of the company for this source"}],"status":409,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"External id used by another record"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"resource","schema":{"enum":["products","categories","customers","warehouses","orders","invoices"],"type":"string"},"example":"products","required":true,"description":"Kind of record: products, categories, customers, warehouses, orders or invoices. The operation needs the write scope of that resource (stock:write for warehouses)."},{"in":"path","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":true,"description":"External system, in lowercase."},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000011","required":true,"description":"Identifier of the record."}],"description":"Sets the external id of the record for one source, replacing the one it had for that source. A record has at most one external id per source: a shop with a product id and a variant id uses two sources (for example shopify_product and shopify_variant). The record itself is not changed.","operationId":"setExternalRef","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRefSet"},"examples":{"example":{"value":{"external_id":"1042"},"summary":"Example"}}}},"required":true}},"delete":{"tags":["External ids"],"summary":"Remove the link to an external system","security":[{"bearerAuth":[]}],"x-scopes":["products:write","categories:write","customers:write","stock:write","orders:write","invoices:write"],"responses":{"204":{"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Removed."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:write","categories:write","customers:write","stock:write","orders:write","invoices:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"value":{"code":"not_found","type":"https://birp.io/developers/errors/not_found","title":"Not found","detail":"The requested resource does not exist.","status":404,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown id, or a record of another company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"No such record for the company of the key. Malformed ids answer the same."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"Idempotency-Key","message":"must be 1 to 128 printable ASCII characters without spaces"}],"status":422,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid header"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products/00000000-0000-4000-8000-000000000011/external-refs/woocommerce","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"resource","schema":{"enum":["products","categories","customers","warehouses","orders","invoices"],"type":"string"},"example":"products","required":true,"description":"Kind of record: products, categories, customers, warehouses, orders or invoices. The operation needs the write scope of that resource (stock:write for warehouses)."},{"in":"path","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":true,"description":"External system, in lowercase."},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"path","name":"id","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-4000-8000-000000000011","required":true,"description":"Identifier of the record. Also answered when the record has no external id for this source."}],"description":"Removes the external id of the record for one source. Only the link is removed, never the record.","operationId":"removeExternalRef"}},"/v1/products/external/{source}/{external_id}":{"put":{"tags":["Products"],"summary":"Create or update a product by its external id","security":[{"bearerAuth":[]}],"x-scopes":["products:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000011","sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","status":"active","barcode":"2000000000015","currency":"MDL","image_url":null,"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"category_id":"00000000-0000-4000-8000-000000000021","external_ids":[{"source":"woocommerce","external_id":"1042"}]}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Updated."},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000011","sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","status":"active","barcode":"2000000000015","currency":"MDL","image_url":null,"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","archived_at":null,"category_id":"00000000-0000-4000-8000-000000000021","external_ids":[{"source":"woocommerce","external_id":"1042"}]}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Created."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["products:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"sku_taken":{"value":{"code":"sku_taken","type":"https://birp.io/developers/errors/sku_taken","title":"SKU in use","detail":"Another product of the company already has this SKU.","errors":[{"field":"sku","message":"is used by another product of the company"}],"status":409,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"SKU used by another product"},"barcode_taken":{"value":{"code":"barcode_taken","type":"https://birp.io/developers/errors/barcode_taken","title":"Barcode in use","detail":"Another product of the company already has this barcode.","errors":[{"field":"barcode","message":"is used by another product of the company"}],"status":409,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Barcode used by another product"},"kind_mismatch":{"value":{"code":"kind_mismatch","type":"https://birp.io/developers/errors/kind_mismatch","title":"Product kind mismatch","detail":"The product mapped to this external id is of another kind. The kind of a product never changes.","status":409,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Linked product of another kind"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"reference_not_found":{"value":{"code":"reference_not_found","type":"https://birp.io/developers/errors/reference_not_found","title":"Reference not found","detail":"A reference in the request matches no record of the company.","errors":[{"field":"category","message":"matches no record of the company"}],"status":422,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Unknown category"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/products/external/woocommerce/1042","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":true,"description":"External system, in lowercase."},{"in":"path","name":"external_id","schema":{"type":"string","maxLength":255,"minLength":1},"example":"1042","required":true,"description":"Identifier of the product in that system."},{"$ref":"#/components/parameters/IdempotencyKeyOptional"}],"description":"Finds the product linked to this external id. If none is linked and the body has a SKU that a product of the same kind already has, that product is linked and updated. Otherwise a product is created and linked. On update, the fields sent are written and the others left as they are.","operationId":"upsertProductByExternalId","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpsert"},"examples":{"example":{"value":{"sku":"SP-FLOUR-25","kind":"goods","name":"Wheat flour 25 kg","unit":"kg","price":"12.50","currency":"MDL"},"summary":"Example"}}}},"required":true}}},"/v1/customers/external/{source}/{external_id}":{"put":{"tags":["Customers"],"summary":"Create or update a customer by its external id","security":[{"bearerAuth":[]}],"x-scopes":["customers:write"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000031","name":"Epicerie Exemple SARL","email":"achats@example.com","phone":"+33 0 00 00 00 00","address":{"city":"Paris","line1":"12 rue des Exemples","line2":null,"country":"France","postal_code":"00000"},"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","vat_number":"EXAMPLE-VAT-0002","contact_name":"Claire Exemple","country_code":"FR","external_ids":[{"source":"woocommerce","external_id":"cust-77"}],"customer_type":"b2b","registration_number":"EXAMPLE-0002"}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Updated."},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerItem"},"example":{"data":{"id":"00000000-0000-4000-8000-000000000031","name":"Epicerie Exemple SARL","email":"achats@example.com","phone":"+33 0 00 00 00 00","address":{"city":"Paris","line1":"12 rue des Exemples","line2":null,"country":"France","postal_code":"00000"},"created_at":"2026-09-01T07:30:00.000Z","updated_at":"2026-09-28T14:05:12.417Z","vat_number":"EXAMPLE-VAT-0002","contact_name":"Claire Exemple","country_code":"FR","external_ids":[{"source":"woocommerce","external_id":"cust-77"}],"customer_type":"b2b","registration_number":"EXAMPLE-0002"}}}},"headers":{"Location":{"schema":{"type":"string"},"description":"Path of the created resource (201 only)."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per minute, for the key or its company, whichever has fewer left."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the limit resets."},"Idempotency-Replayed":{"schema":{"type":"string"},"description":"true when this is the stored response of an earlier request with the same Idempotency-Key."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests you can still send before the limit is reached."}},"description":"Created."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"invalid_json":{"value":{"code":"invalid_json","type":"https://birp.io/developers/errors/invalid_json","title":"Invalid JSON","detail":"The request body is not valid JSON.","status":400,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Malformed JSON"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not valid JSON."},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"api_key_expired":{"value":{"code":"api_key_expired","type":"https://birp.io/developers/errors/api_key_expired","title":"API key expired","detail":"The API key has expired. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Expired key"},"api_key_invalid":{"value":{"code":"api_key_invalid","type":"https://birp.io/developers/errors/api_key_invalid","title":"API key invalid","detail":"The API key is malformed or unknown.","status":401,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid key"},"api_key_missing":{"value":{"code":"api_key_missing","type":"https://birp.io/developers/errors/api_key_missing","title":"API key missing","detail":"Send the API key in the Authorization header: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"No Authorization header"},"api_key_revoked":{"value":{"code":"api_key_revoked","type":"https://birp.io/developers/errors/api_key_revoked","title":"API key revoked","detail":"The API key has been revoked. Create a new key in BIRP settings.","status":401,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Revoked key"},"test_key_not_supported":{"value":{"code":"test_key_not_supported","type":"https://birp.io/developers/errors/test_key_not_supported","title":"Test keys are not supported","detail":"Test keys (birp_test_) are not available yet. Use a live key.","status":401,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Test key"},"unsupported_auth_scheme":{"value":{"code":"unsupported_auth_scheme","type":"https://birp.io/developers/errors/unsupported_auth_scheme","title":"Unsupported authorization scheme","detail":"The Authorization header must use the Bearer scheme: \"Authorization: Bearer <key>\".","status":401,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not the Bearer scheme"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."},"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer realm=\"BIRP API\"."}},"description":"The request carries no valid key."},"403":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"company_inactive":{"value":{"code":"company_inactive","type":"https://birp.io/developers/errors/company_inactive","title":"Company inactive","detail":"The company account is not active.","status":403,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company inactive"},"company_read_only":{"value":{"code":"company_read_only","type":"https://birp.io/developers/errors/company_read_only","title":"Company read only","detail":"The company account is read only: data can be read but not changed.","status":403,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company read only"},"company_suspended":{"value":{"code":"company_suspended","type":"https://birp.io/developers/errors/company_suspended","title":"Company suspended","detail":"The company account is suspended.","status":403,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Company suspended"},"insufficient_scope":{"value":{"code":"insufficient_scope","type":"https://birp.io/developers/errors/insufficient_scope","title":"Insufficient scope","detail":"The API key does not have the scopes this operation requires.","status":403,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","required_scopes":["customers:write"]},"summary":"Missing scope"},"api_access_disabled":{"value":{"code":"api_access_disabled","type":"https://birp.io/developers/errors/api_access_disabled","title":"API access disabled","detail":"API access is not enabled for the company. BIRP support can enable it.","status":403,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"API access not enabled for the company"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The key or its company may not use this operation."},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"external_id_conflict":{"value":{"code":"external_id_conflict","type":"https://birp.io/developers/errors/external_id_conflict","title":"External id in use","detail":"This external id of this source already identifies another record of the company.","errors":[{"field":"external_ids[0]","message":"already identifies another record of the company for this source"}],"status":409,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"External id used by another customer"},"idempotency_in_progress":{"value":{"code":"idempotency_in_progress","type":"https://birp.io/developers/errors/idempotency_in_progress","title":"Request in progress","detail":"A request with the same Idempotency-Key is still being processed. Retry after it ends.","status":409,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Same key still running"},"customer_match_ambiguous":{"value":{"code":"customer_match_ambiguous","type":"https://birp.io/developers/errors/customer_match_ambiguous","title":"Customer match ambiguous","detail":"More than one customer matches. Link the external id to one of them first.","errors":[{"field":"email","message":"matches more than one customer of the company"}],"status":409,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Several customers match"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request conflicts with the current state."},"413":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"payload_too_large":{"value":{"code":"payload_too_large","type":"https://birp.io/developers/errors/payload_too_large","title":"Payload too large","detail":"The request body is larger than the limit.","status":413,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Body too large"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is larger than the limit."},"415":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unsupported_media_type":{"value":{"code":"unsupported_media_type","type":"https://birp.io/developers/errors/unsupported_media_type","title":"Unsupported media type","detail":"Send the request body as JSON, with \"Content-Type: application/json\".","status":415,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Not application/json"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The body is not JSON."},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_failed":{"value":{"code":"validation_failed","type":"https://birp.io/developers/errors/validation_failed","title":"Validation failed","detail":"One or more request parameters are invalid.","errors":[{"field":"price","message":"must be a decimal string such as \"12.50\": JSON numbers are refused because they can lose precision"}],"status":422,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Invalid field"},"idempotency_key_reused":{"value":{"code":"idempotency_key_reused","type":"https://birp.io/developers/errors/idempotency_key_reused","title":"Idempotency-Key reused","detail":"This Idempotency-Key was already used for a different request on this route.","status":422,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee"},"summary":"Key used for another request"}}}},"headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"The request cannot be processed as sent."},"429":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"value":{"code":"rate_limited","type":"https://birp.io/developers/errors/rate_limited","title":"Too many requests","detail":"The rate limit has been reached. Retry after the number of seconds in Retry-After.","status":429,"instance":"/v1/customers/external/woocommerce/cust-77","request_id":"a1b2c3d4-0000-4000-8000-0000000000ee","limit_scope":"key"},"summary":"Per-key limit reached"}}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"X-Request-Id":{"schema":{"type":"string"},"description":"Identifier of the request. Quote it to support."}},"description":"A rate limit was reached (key, company or client IP)."}},"parameters":[{"in":"path","name":"source","schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"example":"woocommerce","required":true,"description":"External system, in lowercase."},{"in":"path","name":"external_id","schema":{"type":"string","maxLength":255,"minLength":1},"example":"cust-77","required":true,"description":"Identifier of the customer in that system."},{"$ref":"#/components/parameters/IdempotencyKeyOptional"},{"in":"query","name":"match_by","schema":{"type":"string","pattern":"^(email|registration_number)(,(email|registration_number))?$"},"example":"email","required":false,"description":"When the external id is not linked yet: email, registration_number, or both separated by a comma, tried in that order."}],"description":"Finds the customer linked to this external id. When none is linked and match_by is given, tries the email (case-insensitive) and then the registration number (trimmed), in the order given; a match is linked and updated. More than one match at a step answers 409. Otherwise the customer is created and linked.","operationId":"upsertCustomerByExternalId","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerUpsert"},"examples":{"example":{"value":{"name":"Epicerie Exemple SARL","email":"achats@example.com","country_code":"FR","customer_type":"b2b"},"summary":"Example"}}}},"required":true}}}},"openapi":"3.1.0","servers":[{"url":"https://api.birp.io","description":"Production"}],"components":{"schemas":{"Me":{"type":"object","required":["company","key","rate_limits"],"properties":{"key":{"allOf":[{"$ref":"#/components/schemas/MeKey"}],"description":"The key of the request."},"company":{"allOf":[{"$ref":"#/components/schemas/MeCompany"}],"description":"Company the key belongs to."},"rate_limits":{"allOf":[{"$ref":"#/components/schemas/MeRateLimits"}],"description":"Rate limits that apply to the key."}}},"MeKey":{"type":"object","required":["prefix","name","scopes","expires_at"],"properties":{"name":{"type":"string","description":"Name given to the key in BIRP."},"prefix":{"type":"string","example":"EXAMPLE-PREFIX","description":"Identifier of the key, as the key list in BIRP shows it."},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes of the key."},"expires_at":{"type":["string","null"],"description":"Expiry of the key. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."}}},"Order":{"type":"object","required":["id","number","document_kind","status","customer_id","ordered_at","expected_at","delivered_at","total","currency","contact","shipping_address","billing_address","source","confirmed_at","notes","lines","external_ids","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Order identifier."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"},"description":"Ordered products."},"notes":{"type":["string","null"],"description":"Notes sent with the order."},"total":{"type":["string","null"],"description":"Order total. Decimal string with two decimals."},"number":{"type":"string","description":"Order number, unique per company."},"source":{"type":["string","null"],"description":"System the order came from, for example woocommerce. Null for orders made in BIRP."},"status":{"enum":["draft","confirmed","in_production","ready","prepared","in_delivery","delivered","cancelled","returned"],"type":"string","description":"Status of the order. Treat a value outside this list as unknown."},"contact":{"allOf":[{"$ref":"#/components/schemas/Contact"}],"description":"Contact person of the customer for this order."},"currency":{"type":["string","null"],"description":"ISO 4217 code of the order; null when the order has none."},"created_at":{"type":"string","description":"Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"ordered_at":{"type":["string","null"],"description":"Order date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"updated_at":{"type":"string","description":"Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"customer_id":{"type":["string","null"],"format":"uuid","description":"Customer of the order."},"expected_at":{"type":["string","null"],"description":"Expected delivery date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"confirmed_at":{"type":["string","null"],"description":"Confirmation time, or null. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"delivered_at":{"type":["string","null"],"description":"Delivery date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Identifiers of the order in external systems."},"document_kind":{"enum":["order",null],"type":["string","null"],"description":"order, for an order or for a quote that became an order when it was confirmed. Quotes that are not confirmed are not listed."},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}],"description":"Billing address sent with the order; null when none was sent."},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}],"description":"Shipping address sent with the order; null when none was sent."}}},"Party":{"type":"object","required":["name","address","city","postal_code","country","vat_number","registration_number"],"properties":{"city":{"type":["string","null"],"description":"City."},"name":{"type":["string","null"],"description":"Name, as printed on the invoice."},"address":{"type":["string","null"],"description":"Address."},"country":{"type":["string","null"],"description":"Country, as printed."},"vat_number":{"type":["string","null"],"description":"VAT number."},"postal_code":{"type":["string","null"],"description":"Postal code."},"registration_number":{"type":["string","null"],"description":"Registration number."}}},"MeItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Me"}],"description":"The company and key of the request."}}},"Address":{"type":"object","required":["line1","line2","postal_code","city","country"],"properties":{"city":{"type":["string","null"],"description":"City."},"line1":{"type":["string","null"],"description":"First address line."},"line2":{"type":["string","null"],"description":"Second address line."},"country":{"type":["string","null"],"description":"Country, free text (a country name in the language of the company, or a code)."},"postal_code":{"type":["string","null"],"description":"Postal code."}}},"Contact":{"type":"object","required":["name","phone","email"],"properties":{"name":{"type":["string","null"],"description":"Name of the contact person for the order."},"email":{"type":["string","null"],"description":"Email of the contact person."},"phone":{"type":["string","null"],"description":"Phone of the contact person."}}},"Invoice":{"type":"object","required":["id","number","type","status","issued_at","supplied_at","due_at","paid_at","currency","subtotal","total_discount","total_vat","total","vat_exemption_reason","vat_exemption_text","seller","buyer","customer_id","order_id","related_invoice_id","payment","payment_status","amount_paid","amount_due","notes","legal_footer","lines","vat_breakdown","external_ids","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Invoice identifier."},"type":{"enum":["invoice","credit_note","proforma"],"type":"string","description":"Document type."},"buyer":{"allOf":[{"$ref":"#/components/schemas/Party"}],"description":"Buyer, as printed on the invoice."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"},"description":"Lines, in document order."},"notes":{"type":["string","null"],"description":"Notes printed on the invoice."},"total":{"type":"string","description":"Total including VAT. Decimal string with two decimals."},"due_at":{"type":["string","null"],"description":"Due date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"number":{"type":["string","null"],"description":"Invoice number. Null for a draft written through the API: it gets the next number of the series when it is issued."},"seller":{"allOf":[{"$ref":"#/components/schemas/Party"}],"description":"Seller, as printed on the invoice."},"status":{"enum":["draft","issued","sent","partially_paid","paid","overdue","cancelled","refunded"],"type":"string","description":"Status of the document."},"paid_at":{"type":["string","null"],"description":"Date the invoice was marked paid. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"payment":{"allOf":[{"$ref":"#/components/schemas/InvoicePaymentTerms"}],"description":"Payment terms printed on the invoice."},"currency":{"type":"string","description":"Currency of the invoice."},"order_id":{"type":["string","null"],"format":"uuid","description":"Order the invoice was made from."},"subtotal":{"type":"string","description":"Total excluding VAT. Decimal string with two decimals."},"issued_at":{"type":["string","null"],"description":"Issue date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"total_vat":{"type":"string","description":"Total VAT. Decimal string with two decimals."},"amount_due":{"type":"string","description":"Total minus amount_paid. Decimal string with two decimals."},"created_at":{"type":"string","description":"Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"updated_at":{"type":"string","description":"Last change, including payments recorded against the invoice. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"amount_paid":{"type":"string","description":"Sum of the confirmed payments. Decimal string with two decimals."},"customer_id":{"type":["string","null"],"format":"uuid","description":"Customer record of the buyer."},"supplied_at":{"type":["string","null"],"description":"Supply date. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Identifiers of the invoice in external systems."},"legal_footer":{"type":["string","null"],"description":"Legal footer printed on the invoice."},"vat_breakdown":{"type":"array","items":{"$ref":"#/components/schemas/VatBreakdownEntry"},"description":"Totals per VAT rate."},"payment_status":{"enum":["unpaid","partially_paid","paid","overpaid"],"type":"string","description":"Derived from the confirmed payments of the invoice."},"total_discount":{"type":"string","description":"Total discount. Decimal string with two decimals."},"related_invoice_id":{"type":["string","null"],"format":"uuid","description":"Invoice this document corrects (credit notes)."},"vat_exemption_text":{"type":["string","null"],"description":"Exemption text printed on the invoice."},"vat_exemption_reason":{"enum":["intra_community","export","reverse_charge","small_business","other",null],"type":["string","null"],"description":"VAT exemption of the document; null when none."}}},"Problem":{"type":"object","required":["type","title","status","detail","instance","code","request_id"],"properties":{"code":{"type":"string","example":"not_found","description":"Stable error code, the last segment of type."},"type":{"type":"string","example":"https://birp.io/developers/errors/not_found","description":"URI of the documentation page of this error code."},"title":{"type":"string","example":"Not found","description":"Short summary of the error code."},"detail":{"type":"string","description":"Explanation for this occurrence. Never repeats request input."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ProblemFieldError"},"description":"Each parameter, header or body field at fault, with its path and a message."},"status":{"type":"number","example":404,"description":"HTTP status code."},"instance":{"type":"string","example":"/v1/products/00000000-0000-4000-8000-000000000011","description":"Path of the request."},"request_id":{"type":"string","description":"Identifier of the request, also sent in the X-Request-Id header. Quote it to support."},"limit_scope":{"enum":["key","company","ip"],"type":"string","description":"Which limit was reached (rate_limited only)."},"required_scopes":{"type":"array","items":{"type":"string"},"description":"Scopes the operation requires (insufficient_scope only)."}}},"Product":{"type":"object","required":["id","kind","sku","name","barcode","unit","category_id","price","currency","status","archived_at","image_url","external_ids","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Product identifier."},"sku":{"type":"string","description":"Reference of the product. A goods item and a finished product can share one; a reference by sku then needs kind."},"kind":{"enum":["goods","finished_product"],"type":"string","description":"goods: bought and resold. finished_product: produced by the company."},"name":{"type":"string","description":"Product name."},"unit":{"type":["string","null"],"description":"Default unit of measure, free text (for example kg or pcs)."},"price":{"type":["string","null"],"description":"Sale price. Decimal string with two decimals."},"status":{"enum":["active","archived"],"type":"string","description":"archived when the product was archived in BIRP."},"barcode":{"type":["string","null"],"description":"Barcode of the product."},"currency":{"type":["string","null"],"description":"Currency of the price, an uppercase ISO 4217 code."},"image_url":{"type":["string","null"],"description":"Temporary URL of the product image: it expires, so read it again instead of storing it. Finished products only."},"created_at":{"type":"string","description":"Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"updated_at":{"type":"string","description":"Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"archived_at":{"type":["string","null"],"description":"When the product was archived. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"category_id":{"type":["string","null"],"format":"uuid","description":"Category of the product."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Identifiers of the product in external systems."}}},"TaxCode":{"type":"object","required":["code","rate","label","effective_from","effective_to"],"properties":{"code":{"type":"string","example":"STANDARD","description":"The value to send as tax_code on invoice lines. Codes follow the rules of the company's country; they are not fixed names."},"rate":{"type":["string","null"],"example":"20.0000","description":"Rate in percent, decimal string with four decimals; null for an exempt rule (no VAT)."},"label":{"type":"string","description":"Legal basis of the code under the rules of the company's country. It is the only description a code has."},"effective_to":{"type":["string","null"],"description":"Day the rule stops applying, YYYY-MM-DD; null while it applies."},"effective_from":{"type":"string","example":"2015-01-01","description":"First day the rule applies, YYYY-MM-DD."}},"description":"A tax code under the rules of the company's country, valid at the date asked."},"Category":{"type":"object","required":["id","name","description","product_kind","external_ids","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Category identifier."},"name":{"type":"string","description":"Category name."},"created_at":{"type":"string","description":"Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"updated_at":{"type":"string","description":"Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"description":{"type":["string","null"],"description":"Category description."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Identifiers of the category in external systems."},"product_kind":{"enum":["goods","finished_product"],"type":"string","description":"Kind of the products the category groups."}}},"Customer":{"type":"object","required":["id","name","email","phone","contact_name","address","registration_number","vat_number","customer_type","country_code","external_ids","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Customer identifier."},"name":{"type":"string","description":"Customer name."},"email":{"type":["string","null"],"description":"Contact email. Two customers can share one."},"phone":{"type":["string","null"],"description":"Contact phone."},"address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"description":"Postal address."},"created_at":{"type":"string","description":"Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"updated_at":{"type":"string","description":"Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"vat_number":{"type":["string","null"],"description":"VAT number, null when the customer has none."},"contact_name":{"type":["string","null"],"description":"Name of the contact person."},"country_code":{"type":["string","null"],"example":"FR","description":"ISO 3166-1 alpha-2 country code, next to the free-text address.country. Null when not recorded."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Identifiers of the customer in external systems."},"customer_type":{"enum":["b2b","b2c",null],"type":["string","null"],"description":"b2b for a company, b2c for a private person. Null when not recorded."},"registration_number":{"type":["string","null"],"description":"Company registration or tax number, in the format of its country."}}},"PageMeta":{"type":"object","required":["next_cursor","has_more","limit"],"properties":{"limit":{"type":"number","example":50,"description":"Page size used for this response."},"has_more":{"type":"boolean","description":"True when another page exists."},"next_cursor":{"type":["string","null"],"description":"Cursor of the next page, to pass as the cursor parameter. Null on the last page."}}},"MeCompany":{"type":"object","required":["id","name","base_currency","country_code"],"properties":{"id":{"type":"string","format":"uuid","description":"Company identifier."},"name":{"type":"string","description":"Company name."},"country_code":{"type":["string","null"],"example":"MD","description":"ISO 3166-1 alpha-2 country of the company. Its tax codes follow the rules of that country. Null when the company has no country set."},"base_currency":{"type":["string","null"],"example":"MDL","description":"ISO 4217 code of the company base currency: the currency of orders and invoices sent without one. Null when the company has none set."}}},"OrderItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Order"}],"description":"The order."}}},"OrderLine":{"type":"object","required":["product_id","product_kind","sku","name","quantity","unit","unit_price","description"],"properties":{"sku":{"type":["string","null"],"description":"Product reference at the time of the order."},"name":{"type":["string","null"],"description":"Product name at the time of the order."},"unit":{"type":["string","null"],"description":"Unit of the quantity."},"quantity":{"type":["string","null"],"description":"Ordered quantity, decimal string, or null; when it is null, quantity_raw gives the quantity as text."},"product_id":{"type":["string","null"],"format":"uuid","description":"Product of the line; null when the line names no product."},"unit_price":{"type":["string","null"],"description":"Unit price, decimal string with four decimals; null when the line has no price."},"description":{"type":["string","null"],"description":"Line description sent with the order, if any."},"product_kind":{"enum":["finished_product","intermediate_product",null],"type":["string","null"],"description":"Kind of the product; null without product_id. intermediate_product: a product the company makes for use in its own production."},"quantity_raw":{"type":"string","description":"The quantity as text, present only when quantity is null."}}},"OrderPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"},"description":"Orders of the page, ordered by id."},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Pagination."}}},"Reference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"BIRP id of the record."},"source":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$","description":"External system of external_id, in lowercase."},"external_id":{"type":"string","maxLength":255,"description":"Identifier of the record in an external system. Requires source."}},"description":"Another record of the company: exactly one of id, or external_id with source."},"Warehouse":{"type":"object","required":["id","name","address","kind","status","archived_at","external_ids","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Warehouse identifier."},"kind":{"enum":["warehouse","retail"],"type":"string","description":"retail: the warehouse of a shop."},"name":{"type":"string","description":"Name, unique per company."},"status":{"enum":["active","archived"],"type":"string","description":"archived when the warehouse was archived in BIRP."},"address":{"type":["string","null"],"description":"Address, free text."},"created_at":{"type":"string","description":"Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"updated_at":{"type":"string","description":"Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"archived_at":{"type":["string","null"],"description":"When the warehouse was archived. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Identifiers of the warehouse in external systems."}}},"ExternalId":{"type":"object","required":["source","external_id"],"properties":{"source":{"type":"string","example":"woocommerce","description":"System that owns the identifier, in lowercase (for example woocommerce or shopify)."},"external_id":{"type":"string","example":"1042","description":"Identifier of the record in that system."}}},"StockLevel":{"type":"object","required":["id","product_id","product_kind","warehouse_id","quantity","unit","lot_count"],"properties":{"id":{"type":"string","description":"Identifier of the row, stable while the row exists. Treat it as opaque text."},"unit":{"type":"string","description":"Unit of the quantity."},"quantity":{"type":["string","null"],"description":"Quantity on hand in the warehouse, in this unit. Decimal string, at most three decimals, or null; when it is null, quantity_raw gives the quantity as text."},"lot_count":{"type":"number","description":"Number of lots counted."},"product_id":{"type":"string","format":"uuid","description":"Product identifier."},"product_kind":{"enum":["goods","finished_product"],"type":"string","description":"Kind of the product."},"quantity_raw":{"type":"string","description":"The quantity as text, present only when quantity is null."},"warehouse_id":{"type":["string","null"],"format":"uuid","description":"Warehouse of the stock, or null when the stock is not assigned to one."}}},"BatchResult":{"type":"object","required":["results","summary"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/BatchResultItem"}},"summary":{"$ref":"#/components/schemas/BatchSummary"}},"description":"Per-item results of a batch. Items that succeeded are written even when others failed."},"ExternalRef":{"type":"object","required":["resource","id","source","external_id"],"properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","example":"woocommerce"},"resource":{"enum":["products","categories","customers","warehouses","orders","invoices"],"type":"string"},"external_id":{"type":"string","example":"1042"}},"description":"The external id of a record for one source."},"InvoiceItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Invoice"}],"description":"The invoice."}}},"InvoiceLine":{"type":"object","required":["id","position","description","details","product_id","product_kind","lot_number","quantity","unit","unit_price","discount","line_total","vat_rate","vat_amount"],"properties":{"id":{"type":"string","format":"uuid","description":"Line identifier. Line ids change when the invoice is edited in BIRP."},"unit":{"type":"string","description":"Unit of the quantity."},"details":{"type":["string","null"],"description":"Additional details."},"discount":{"type":"string","description":"Discount amount. Decimal string with two decimals."},"position":{"type":"number","description":"Position of the line on the invoice."},"quantity":{"type":"string","description":"Quantity, decimal string with four decimals."},"vat_rate":{"type":"string","description":"VAT rate in percent."},"line_total":{"type":"string","description":"Line total excluding VAT. Decimal string with two decimals."},"lot_number":{"type":["string","null"],"description":"Lot number."},"product_id":{"type":["string","null"],"format":"uuid","description":"Product of the line."},"unit_price":{"type":"string","description":"Unit price excluding VAT, decimal string with four decimals."},"vat_amount":{"type":"string","description":"VAT amount of the line. Decimal string with two decimals."},"description":{"type":"string","description":"Line description."},"product_kind":{"enum":["goods","finished_product",null],"type":["string","null"],"description":"Kind of the product."}}},"InvoicePage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"},"description":"Invoices of the page, ordered by id."},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Pagination."}}},"OrderCancel":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","example":"Cancelled by the customer in the shop","maxLength":500,"minLength":1}},"description":"Why the order is cancelled; kept in the order history."},"OrderCreate":{"type":"object","required":["lines"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLineCreate"},"maxItems":200,"minItems":1},"notes":{"type":["string","null"],"maxLength":2000},"source":{"type":"string","example":"woocommerce","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$","description":"System the order comes from, in lowercase. Sent with external_id."},"currency":{"type":"string","example":"USD","description":"ISO 4217 code. Left out on create: the company base currency."},"customer":{"allOf":[{"$ref":"#/components/schemas/Reference"}],"description":"An existing customer of the company."},"ordered_at":{"type":"string","example":"2026-09-27T08:00:00Z","description":"When the order was placed, ISO 8601 date and time with an offset or Z. Left out: now."},"expected_at":{"type":"string","example":"2026-09-29T06:00:00Z","description":"Expected delivery, ISO 8601 date and time with an offset or Z. Left out on create: ordered_at."},"external_id":{"type":"string","example":"order-5512","maxLength":255,"description":"Order number in that system. Linked as the order external id: the same order cannot be imported twice."},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddressInput"},{"type":"null"}]},"customer_upsert":{"allOf":[{"$ref":"#/components/schemas/CustomerUpsertInline"}],"description":"A customer created or updated with the order, by its external id. Needs customers:write as well."},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddressInput"},{"type":"null"}]}},"description":"A new customer order, created in draft. Send exactly one of customer and customer_upsert."},"OrderUpdate":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLineCreate"},"maxItems":200,"minItems":1},"notes":{"type":["string","null"],"maxLength":2000},"currency":{"type":"string","example":"USD","description":"ISO 4217 code. Left out on create: the company base currency."},"expected_at":{"type":"string","example":"2026-09-29T06:00:00Z","description":"Expected delivery, ISO 8601 date and time with an offset or Z. Left out on create: ordered_at."},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddressInput"},{"type":"null"}]},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddressInput"},{"type":"null"}]}},"description":"Changes to a draft order; fields left out are not touched. Lines, when sent, replace all lines."},"ProductItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Product"}],"description":"The product."}}},"ProductPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"description":"Products of the page, ordered by id."},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Pagination."}}},"TaxCodeList":{"type":"object","required":["data","date"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxCode"}},"date":{"type":"string","example":"2026-10-05","description":"The date the codes are valid for, YYYY-MM-DD."}},"description":"Every VAT code valid at the date, in one page."},"BatchSummary":{"type":"object","required":["created","updated","failed"],"properties":{"failed":{"type":"number","example":1},"created":{"type":"number","example":1},"updated":{"type":"number","example":1}}},"CategoryItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Category"}],"description":"The category."}}},"CategoryPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"},"description":"Categories of the page, ordered by id."},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Pagination."}}},"CustomerItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Customer"}],"description":"The customer."}}},"CustomerPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"},"description":"Customers of the page, ordered by id."},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Pagination."}}},"InvoiceIssue":{"type":"object","properties":{"issue_date":{"type":"string","example":"2026-10-05","description":"Issue date, YYYY-MM-DD. The VAT is recomputed for it."}},"description":"Optional issue date; send {} or no body for the company today."},"MeRateLimits":{"type":"object","required":["per_key_per_minute","per_company_per_minute","window_seconds"],"properties":{"window_seconds":{"type":"number","description":"Length of a rate limit window, in seconds."},"per_key_per_minute":{"type":"number","description":"Requests allowed per minute for this key."},"per_company_per_minute":{"type":"number","description":"Requests allowed per minute for all keys of the company together."}}},"OrderAddress":{"type":"object","required":["name","company","line1","line2","postal_code","city","region","country_code","phone","email"],"properties":{"city":{"type":["string","null"],"example":"Springfield","maxLength":100},"name":{"type":["string","null"],"example":"Jordan Example","maxLength":200},"email":{"type":["string","null"],"example":"jordan.example@example.org","maxLength":200},"line1":{"type":["string","null"],"example":"100 Example Street","maxLength":200},"line2":{"type":["string","null"],"maxLength":200},"phone":{"type":["string","null"],"example":"+1 000 000 0000","maxLength":50},"region":{"type":["string","null"],"maxLength":100},"company":{"type":["string","null"],"maxLength":200,"description":"Company name, null for a private person."},"postal_code":{"type":["string","null"],"example":"00000","maxLength":20},"country_code":{"type":["string","null"],"example":"US","description":"ISO 3166-1 alpha-2."}},"description":"Billing or shipping address of an order, as sent. Every member may be null."},"OrderConfirm":{"type":"object","properties":{},"description":"No member: send {} or no body."},"CustomerMatch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"match_by":{"type":"array","items":{"enum":["email","registration_number"],"type":"string"},"description":"Matching to try, in order, when the external id is not linked yet."},"external_id":{"type":"string","maxLength":255}},"description":"How to find the customer: id (must exist), or external_id with source. With external_id, match_by also tries email and then registration_number when no customer is linked yet."},"InvoiceCreate":{"type":"object","required":["customer","lines"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineCreate"},"maxItems":200,"minItems":1},"notes":{"type":["string","null"],"maxLength":2000},"order":{"anyOf":[{"$ref":"#/components/schemas/Reference"},{"type":"null"}],"description":"An order of the company this invoice bills."},"currency":{"type":"string","example":"MDL","description":"ISO 4217 code. Left out on create: the company base currency."},"customer":{"allOf":[{"$ref":"#/components/schemas/Reference"}],"description":"The customer billed. Its name, address and fiscal ids become the buyer details of the invoice."},"due_date":{"type":["string","null"],"example":"2026-11-04","description":"Due date, YYYY-MM-DD. Left out: issue date plus payment_terms_days, when given."},"issue_date":{"type":"string","example":"2026-10-05","description":"Document date the VAT is computed for, YYYY-MM-DD. Left out: the company today. Issuing sets the issue date again (the issue_date sent then, or the company today) and recomputes the VAT for it."},"supply_date":{"type":["string","null"],"example":"2026-10-05","description":"Date of supply, YYYY-MM-DD."},"payment_terms_days":{"type":["number","null"],"example":30,"maximum":365,"minimum":0},"vat_exemption_text":{"type":["string","null"],"maxLength":500,"description":"Legal mention printed with the exemption."},"vat_exemption_reason":{"enum":["intra_community","export","reverse_charge","small_business","other",null],"type":["string","null"],"description":"Why VAT is zero, for the whole invoice. A zero-rate code with a right to deduct (export, intra-community, reverse charge) needs the matching reason; otherwise the line answers tax_code_mismatch."}},"description":"A new invoice, created as a draft with its totals and VAT computed by BIRP."},"InvoiceUpdate":{"type":"object","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLineCreate"},"maxItems":200,"minItems":1},"notes":{"type":["string","null"],"maxLength":2000},"order":{"anyOf":[{"$ref":"#/components/schemas/Reference"},{"type":"null"}],"description":"An order of the company this invoice bills."},"currency":{"type":"string","example":"MDL","description":"ISO 4217 code. Left out on create: the company base currency."},"customer":{"$ref":"#/components/schemas/Reference"},"due_date":{"type":["string","null"],"example":"2026-11-04","description":"Due date, YYYY-MM-DD. Left out: issue date plus payment_terms_days, when given."},"issue_date":{"type":"string","example":"2026-10-05","description":"Document date the VAT is computed for, YYYY-MM-DD. Left out: the company today. Issuing sets the issue date again (the issue_date sent then, or the company today) and recomputes the VAT for it."},"supply_date":{"type":["string","null"],"example":"2026-10-05","description":"Date of supply, YYYY-MM-DD."},"payment_terms_days":{"type":["number","null"],"example":30,"maximum":365,"minimum":0},"vat_exemption_text":{"type":["string","null"],"maxLength":500,"description":"Legal mention printed with the exemption."},"vat_exemption_reason":{"enum":["intra_community","export","reverse_charge","small_business","other",null],"type":["string","null"],"description":"Why VAT is zero, for the whole invoice. A zero-rate code with a right to deduct (export, intra-community, reverse charge) needs the matching reason; otherwise the line answers tax_code_mismatch."}},"description":"Changes to a draft; fields left out are not touched. Lines, when sent, replace all lines. Totals and VAT are recomputed."},"ProductCreate":{"type":"object","required":["kind","name"],"properties":{"sku":{"type":"string","example":"SP-FLOUR-25","maxLength":100,"minLength":1,"description":"Product reference. A write refuses a SKU that another product of the company already has, of either kind. Left out on create: generated by the company numbering."},"kind":{"enum":["goods","finished_product"],"type":"string","description":"goods (bought and resold) or finished_product (made by the company). Never changes."},"name":{"type":"string","example":"Wheat flour 25 kg","maxLength":255,"minLength":1,"description":"Product name."},"unit":{"type":["string","null"],"example":"pcs","maxLength":32,"description":"Unit of sale, free text as in BIRP (for example pcs, kg)."},"price":{"type":["string","null"],"example":"14.90","description":"Sale price, decimal string with at most two decimals. Use prices up to 99999.99: a larger price can be refused with 422 validation_failed."},"barcode":{"type":["string","null"],"example":"2000000000015","maxLength":64,"description":"Barcode, unique in the company across all products. Null removes it."},"category":{"anyOf":[{"$ref":"#/components/schemas/Reference"},{"type":"null"}],"description":"Category of the same kind as the product. Null removes it."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 code of the price. Left out on create: the company currency."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalIdInput"},"maxItems":10,"description":"Identifiers in external systems, at most one per source."}},"description":"A new goods item or finished product."},"ProductUpdate":{"type":"object","properties":{"sku":{"type":"string","example":"SP-FLOUR-25","maxLength":100,"minLength":1,"description":"Product reference. A write refuses a SKU that another product of the company already has, of either kind. Left out on create: generated by the company numbering."},"name":{"type":"string","maxLength":255,"minLength":1,"description":"Product name."},"unit":{"type":["string","null"],"example":"pcs","maxLength":32,"description":"Unit of sale, free text as in BIRP (for example pcs, kg)."},"price":{"type":["string","null"],"example":"14.90","description":"Sale price, decimal string with at most two decimals. Use prices up to 99999.99: a larger price can be refused with 422 validation_failed."},"status":{"enum":["active","archived"],"type":"string","description":"archived hides the product from new documents in BIRP; active restores it."},"barcode":{"type":["string","null"],"example":"2000000000015","maxLength":64,"description":"Barcode, unique in the company across all products. Null removes it."},"category":{"anyOf":[{"$ref":"#/components/schemas/Reference"},{"type":"null"}],"description":"Category of the same kind as the product. Null removes it."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 code of the price. Left out on create: the company currency."}},"description":"Fields to change; fields left out are not touched."},"ProductUpsert":{"type":"object","required":["kind","name"],"properties":{"sku":{"type":"string","example":"SP-FLOUR-25","maxLength":100,"minLength":1,"description":"Product reference. A write refuses a SKU that another product of the company already has, of either kind. Left out on create: generated by the company numbering."},"kind":{"enum":["goods","finished_product"],"type":"string","description":"goods (bought and resold) or finished_product (made by the company). Never changes."},"name":{"type":"string","example":"Wheat flour 25 kg","maxLength":255,"minLength":1,"description":"Product name."},"unit":{"type":["string","null"],"example":"pcs","maxLength":32,"description":"Unit of sale, free text as in BIRP (for example pcs, kg)."},"price":{"type":["string","null"],"example":"14.90","description":"Sale price, decimal string with at most two decimals. Use prices up to 99999.99: a larger price can be refused with 422 validation_failed."},"status":{"enum":["active","archived"],"type":"string","description":"archived or active."},"barcode":{"type":["string","null"],"example":"2000000000015","maxLength":64,"description":"Barcode, unique in the company across all products. Null removes it."},"category":{"anyOf":[{"$ref":"#/components/schemas/Reference"},{"type":"null"}],"description":"Category of the same kind as the product. Null removes it."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 code of the price. Left out on create: the company currency."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalIdInput"},"maxItems":10,"description":"Identifiers in external systems, at most one per source."}},"description":"A product by its external id: created when unknown, otherwise updated with the fields sent (fields left out are not touched)."},"StockMovement":{"type":"object","required":["id","lot_id","type","quantity"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"enum":["receipt","adjustment","loss"],"type":"string","description":"Movement type."},"lot_id":{"type":"string","format":"uuid","description":"Lot the movement changed."},"quantity":{"type":"string","example":"24.000","description":"Signed decimal string, three decimals: positive adds, negative takes."}},"description":"One movement written by an adjustment."},"WarehousePage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Warehouse"},"description":"Warehouses of the page, ordered by id."},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Pagination."}}},"CategoryCreate":{"type":"object","required":["name","product_kind"],"properties":{"name":{"type":"string","example":"Flours","maxLength":255,"minLength":1,"description":"Category name, unique per kind in the company."},"description":{"type":["string","null"],"example":"Wheat and rye flours","maxLength":2000},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalIdInput"},"maxItems":10},"product_kind":{"enum":["goods","finished_product"],"type":"string","description":"Kind of the products it groups. Never changes."}},"description":"A new product category."},"CategoryUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"minLength":1},"description":{"type":["string","null"],"maxLength":2000}},"description":"Fields to change; the kind never changes."},"CustomerCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Epicerie Exemple SARL","maxLength":200,"minLength":1},"email":{"type":["string","null"],"example":"achats@example.com","maxLength":200},"phone":{"type":["string","null"],"example":"+33 0 00 00 00 00","maxLength":50},"address":{"$ref":"#/components/schemas/CustomerAddressInput"},"vat_number":{"type":["string","null"],"example":"EXAMPLE-VAT-0002","maxLength":50},"contact_name":{"type":["string","null"],"example":"Claire Exemple","maxLength":200},"country_code":{"type":["string","null"],"example":"FR","description":"ISO 3166-1 alpha-2 country code."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalIdInput"},"maxItems":10,"description":"Identifiers in external systems, at most one per source."},"customer_type":{"enum":["b2b","b2c",null],"type":["string","null"],"description":"b2b for a company, b2c for a private person."},"registration_number":{"type":["string","null"],"example":"EXAMPLE-0002","maxLength":50,"description":"Registration or tax number, as used in the country."}},"description":"A new customer."},"CustomerUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":200,"minLength":1},"email":{"type":["string","null"],"example":"achats@example.com","maxLength":200},"phone":{"type":["string","null"],"example":"+33 0 00 00 00 00","maxLength":50},"address":{"$ref":"#/components/schemas/CustomerAddressInput"},"vat_number":{"type":["string","null"],"example":"EXAMPLE-VAT-0002","maxLength":50},"contact_name":{"type":["string","null"],"example":"Claire Exemple","maxLength":200},"country_code":{"type":["string","null"],"example":"FR","description":"ISO 3166-1 alpha-2 country code."},"customer_type":{"enum":["b2b","b2c",null],"type":["string","null"],"description":"b2b for a company, b2c for a private person."},"registration_number":{"type":["string","null"],"example":"EXAMPLE-0002","maxLength":50,"description":"Registration or tax number, as used in the country."}},"description":"Fields to change; fields left out are not touched, null clears a field."},"CustomerUpsert":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Epicerie Exemple SARL","maxLength":200,"minLength":1},"email":{"type":["string","null"],"example":"achats@example.com","maxLength":200},"phone":{"type":["string","null"],"example":"+33 0 00 00 00 00","maxLength":50},"address":{"$ref":"#/components/schemas/CustomerAddressInput"},"vat_number":{"type":["string","null"],"example":"EXAMPLE-VAT-0002","maxLength":50},"contact_name":{"type":["string","null"],"example":"Claire Exemple","maxLength":200},"country_code":{"type":["string","null"],"example":"FR","description":"ISO 3166-1 alpha-2 country code."},"external_ids":{"type":"array","items":{"$ref":"#/components/schemas/ExternalIdInput"},"maxItems":10,"description":"Identifiers in external systems, at most one per source."},"customer_type":{"enum":["b2b","b2c",null],"type":["string","null"],"description":"b2b for a company, b2c for a private person."},"registration_number":{"type":["string","null"],"example":"EXAMPLE-0002","maxLength":50,"description":"Registration or tax number, as used in the country."}},"description":"A customer by its external id: created when no customer matches, otherwise updated with the fields sent."},"ExternalRefSet":{"type":"object","required":["external_id"],"properties":{"external_id":{"type":"string","example":"1042","maxLength":255,"minLength":1,"description":"Identifier of the record in the external system."}},"description":"The external id to link to the record for the source of the path."},"InvoicePayment":{"type":"object","required":["id","invoice_id","amount","currency","paid_on","method","reference","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"64.50","description":"Decimal string, two decimals."},"method":{"enum":["bank_transfer","cash","card","cheque","direct_debit","compensation","other"],"type":"string"},"status":{"enum":["confirmed"],"type":"string","description":"Payments recorded through the API are confirmed."},"paid_on":{"type":"string","example":"2026-10-07","description":"YYYY-MM-DD."},"currency":{"type":"string","example":"EUR","description":"The invoice currency."},"reference":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO 8601 date and time in UTC."},"invoice_id":{"type":"string","format":"uuid"}},"description":"A payment recorded on an invoice."},"StockLevelPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"},"description":"Stock levels of the page, ordered by id."},"meta":{"allOf":[{"$ref":"#/components/schemas/PageMeta"}],"description":"Pagination."}}},"BatchResultItem":{"type":"object","required":["index","status"],"properties":{"id":{"type":"string","format":"uuid","description":"Id of the record created or updated."},"index":{"type":"number","example":0,"description":"Position of the item in the request, from 0."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/BatchResultError"},"description":"Present when the item failed."},"status":{"enum":["created","updated","failed"],"type":"string"}},"description":"The outcome of one item, in the order of the request."},"ExternalIdInput":{"type":"object","required":["source","external_id"],"properties":{"source":{"type":"string","example":"woocommerce","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$","description":"External system, in lowercase (for example woocommerce, shopify_product)."},"external_id":{"type":"string","example":"1042","maxLength":255,"minLength":1,"description":"Identifier in that system."}},"description":"An identifier of the record in an external system. A record has at most one per source."},"ExternalRefItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/ExternalRef"}],"description":"The external id now set."}}},"OrderLineCreate":{"type":"object","required":["product","quantity","unit_price"],"properties":{"unit":{"type":"string","example":"pcs","maxLength":32,"description":"Unit of the quantity. Left out: the default unit of the product."},"product":{"allOf":[{"$ref":"#/components/schemas/ProductReference"}],"description":"A finished product of the company (orders of resale goods are not supported in this version)."},"quantity":{"type":"string","example":"20","description":"Decimal string, at most three decimals, above zero."},"unit_price":{"type":"string","example":"3.20","description":"Unit price, decimal string, at most four decimals."},"description":{"type":["string","null"],"maxLength":500}},"description":"One ordered product. A product that is not found fails the whole order; products are never created by an order."},"StockAdjustment":{"type":"object","required":["id","product_id","warehouse_id","reason","quantity","unit","reference","note","movements","level","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Identifier of the adjustment; its movements carry it."},"note":{"type":["string","null"]},"unit":{"type":"string","example":"kg"},"level":{"anyOf":[{"$ref":"#/components/schemas/StockLevel"},{"type":"null"}],"description":"Stock of the product in the warehouse and unit after the adjustment, as GET /v1/stock/levels returns it. Null when nothing is left."},"reason":{"enum":["receipt","adjustment","loss"],"type":"string"},"quantity":{"type":"string","example":"24.000","description":"Signed decimal string, three decimals."},"movements":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"},"description":"The movements the adjustment wrote."},"reference":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO 8601 date and time in UTC."},"product_id":{"type":"string","format":"uuid"},"warehouse_id":{"type":"string","format":"uuid"}},"description":"The adjustment as recorded, with the resulting stock level."},"BatchResultError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"reference_not_found","description":"Problem code, as in the error catalogue."},"field":{"type":"string","example":"data.category","description":"Field of the item, when one field is at fault."},"message":{"type":"string","example":"matches no record of the company","description":"What is wrong."}},"description":"Why one item of a batch failed."},"ProductBatchItem":{"type":"object","required":["match","data"],"properties":{"data":{"$ref":"#/components/schemas/ProductUpsert"},"match":{"allOf":[{"$ref":"#/components/schemas/ProductReference"}],"description":"How to find the product: id (must exist), external_id with source, or sku. Not found by external id or SKU: created."}},"description":"One product of a batch, with the key that finds it."},"ProductReference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"BIRP id of the record."},"sku":{"type":"string","maxLength":100,"description":"Product SKU."},"kind":{"enum":["goods","finished_product"],"type":"string","description":"With sku only: which kind of product."},"source":{"type":"string","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$","description":"External system of external_id, in lowercase."},"external_id":{"type":"string","maxLength":255,"description":"Identifier of the record in an external system. Requires source."}},"description":"A product of the company: exactly one of id, external_id with source, or sku. A SKU may match one goods item and one finished product; kind then chooses."},"CustomerBatchItem":{"type":"object","required":["match","data"],"properties":{"data":{"$ref":"#/components/schemas/CustomerUpsert"},"match":{"$ref":"#/components/schemas/CustomerMatch"}},"description":"One customer of a batch, with the key that finds it."},"InvoiceLineCreate":{"type":"object","required":["quantity","unit_price","tax_code"],"properties":{"unit":{"type":"string","example":"pcs","maxLength":32,"description":"Required without product. Left out with a product: its default unit."},"product":{"allOf":[{"$ref":"#/components/schemas/ProductReference"}],"description":"A product of the company. Left out: a free line with a description."},"quantity":{"type":"string","example":"20","description":"Decimal string, at most four decimals, above zero."},"tax_code":{"type":"string","example":"STANDARD","maxLength":64,"description":"Tax code under the rules of the company's country, valid at the document date. GET /v1/tax-codes lists them. The rate, and so the VAT, comes from that code; an exempt code gives no VAT."},"unit_price":{"type":"string","example":"3.20","description":"Unit price excluding VAT, decimal string, at most four decimals."},"description":{"type":"string","example":"White bread 500 g","maxLength":500,"description":"Required without product. Left out with a product: its name."}},"description":"One invoice line: a product of the company, or a free description."},"OrderAddressInput":{"type":"object","properties":{"city":{"type":["string","null"],"maxLength":100},"name":{"type":["string","null"],"maxLength":200},"email":{"type":["string","null"],"maxLength":200},"line1":{"type":["string","null"],"maxLength":200},"line2":{"type":["string","null"],"maxLength":200},"phone":{"type":["string","null"],"maxLength":50},"region":{"type":["string","null"],"maxLength":100},"company":{"type":["string","null"],"maxLength":200},"postal_code":{"type":["string","null"],"maxLength":20},"country_code":{"type":["string","null"],"example":"US","description":"ISO 3166-1 alpha-2."}},"description":"Billing or shipping address of an order. Every member is optional."},"ProblemFieldError":{"type":"object","required":["field","message"],"properties":{"field":{"type":"string","example":"limit","description":"Name of the query parameter."},"message":{"type":"string","example":"must be between 1 and 200","description":"What is wrong with it."}}},"VatBreakdownEntry":{"type":"object","required":["vat_rate","taxable_amount","vat_amount","tax_code"],"properties":{"tax_code":{"type":["string","null"],"description":"Tax code of this VAT rate under the rules of the company's country at the issue date, as GET /v1/tax-codes lists it. The codes in the examples of this document are placeholders. Null when no tax code applies."},"vat_rate":{"type":"string","description":"VAT rate in percent, as on the lines."},"vat_amount":{"type":"string","description":"Sum of the VAT amounts of the lines at this rate. Decimal string with two decimals."},"taxable_amount":{"type":"string","description":"Sum of the line totals at this rate, excluding VAT. Decimal string with two decimals."}}},"InvoicePaymentItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/InvoicePayment"}],"description":"The payment."}}},"BatchResultEnvelope":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/BatchResult"}],"description":"Results of the batch."}}},"InvoicePaymentTerms":{"type":"object","required":["method","terms_days","reference","bank_account"],"properties":{"method":{"enum":["bank_transfer","cash","card","cheque","direct_debit","other",null],"type":["string","null"],"description":"Payment method."},"reference":{"type":["string","null"],"description":"Payment reference to quote."},"terms_days":{"type":["number","null"],"description":"Payment terms in days."},"bank_account":{"type":["string","null"],"description":"Bank account printed on the invoice."}}},"ProductBatchRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProductBatchItem"},"maxItems":100,"minItems":1}},"description":"1 to 100 products, each created or updated on its own: a failed item leaves the others written."},"StockAdjustmentItem":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/StockAdjustment"}],"description":"The adjustment."}}},"CustomerAddressInput":{"type":"object","properties":{"city":{"type":["string","null"],"example":"Paris","maxLength":100},"line1":{"type":["string","null"],"example":"12 rue des Exemples","maxLength":200},"line2":{"type":["string","null"],"maxLength":200},"country":{"type":["string","null"],"example":"France","maxLength":100,"description":"Free text. Send country_code for the ISO code."},"postal_code":{"type":["string","null"],"example":"00000","maxLength":20}},"description":"Postal address; country is free text. Members left out are not touched on update."},"CustomerBatchRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomerBatchItem"},"maxItems":100,"minItems":1}},"description":"1 to 100 customers, each created or updated on its own: a failed item leaves the others written."},"CustomerUpsertInline":{"type":"object","required":["source","external_id","data"],"properties":{"data":{"$ref":"#/components/schemas/CustomerUpsert"},"source":{"type":"string","example":"woocommerce","pattern":"^[a-z0-9][a-z0-9._-]{0,63}$"},"match_by":{"type":"array","items":{"enum":["email","registration_number"],"type":"string"}},"external_id":{"type":"string","example":"cust-77","maxLength":255,"minLength":1}},"description":"A customer created or updated with the order, by its external id. Needs customers:write as well as orders:write."},"InvoicePaymentCreate":{"type":"object","required":["amount","paid_on","method"],"properties":{"notes":{"type":["string","null"],"maxLength":2000},"amount":{"type":"string","example":"64.50","description":"Decimal string, at most two decimals, above zero."},"method":{"enum":["bank_transfer","cash","card","cheque","direct_debit","compensation","other"],"type":"string"},"paid_on":{"type":"string","example":"2026-10-07","description":"Date the payment was received, YYYY-MM-DD."},"reference":{"type":["string","null"],"example":"EXAMPLE-PAY-0042","maxLength":255,"description":"Reference of the payment in the paying system (card transaction, bank reference)."}},"description":"A payment received for an issued invoice, in the invoice currency."},"StockAdjustmentCreate":{"type":"object","required":["product","warehouse","quantity","reason"],"properties":{"note":{"type":["string","null"],"example":"Weekly count","maxLength":2000},"unit":{"type":"string","example":"kg","maxLength":32,"description":"Unit of the quantity. Left out: the default unit of the product."},"reason":{"enum":["receipt","adjustment","loss"],"type":"string","description":"receipt: goods received (quantity above zero). adjustment: a correction, such as a stock count (either sign). loss: damage, theft or expiry (quantity below zero)."},"product":{"allOf":[{"$ref":"#/components/schemas/ProductReference"}],"description":"A goods item of the company. Finished products are not adjusted through the API in this version: their stock comes from production."},"quantity":{"type":"string","example":"24","description":"Signed decimal string, at most three decimals, not zero: positive adds stock, negative takes it."},"reference":{"type":["string","null"],"example":"WC-STOCK-2026-10-05","maxLength":100,"description":"Reference in the calling system, for example a delivery note or a count id. Kept with the movements."},"warehouse":{"allOf":[{"$ref":"#/components/schemas/Reference"}],"description":"An active warehouse of kind warehouse."}},"description":"A change of the stock of one goods item in one warehouse."}},"parameters":{"IdempotencyKey":{"in":"header","name":"Idempotency-Key","schema":{"type":"string","maxLength":128,"minLength":1},"example":"00000000-0000-4000-8000-0000000000a1","required":true,"description":"Unique value for this request (for example a UUID), 1 to 128 printable ASCII characters. A retry with the same key and the same request gets the stored response for 24 hours, with Idempotency-Replayed: true; the same key with a different request answers 422 idempotency_key_reused. Required on POST, optional on PUT, PATCH and DELETE."},"IdempotencyKeyOptional":{"in":"header","name":"Idempotency-Key","schema":{"type":"string","maxLength":128,"minLength":1},"example":"00000000-0000-4000-8000-0000000000a1","required":false,"description":"Unique value for this request (for example a UUID), 1 to 128 printable ASCII characters. A retry with the same key and the same request gets the stored response for 24 hours, with Idempotency-Replayed: true; the same key with a different request answers 422 idempotency_key_reused. Required on POST, optional on PUT, PATCH and DELETE."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key created in BIRP settings, sent as \"Authorization: Bearer $BIRP_API_KEY\".","bearerFormat":"BIRP API key"}}},"externalDocs":{"url":"https://birp.io/developers","description":"Developer documentation"}}