{ "openapi": "3.1.0", "info": { "title": "Billstack", "version": "1.0.0", "description": "# Billstack Merchant API\n\nRead your own Billstack data \u2014 products, stock, orders, documents and customers \u2014 and update tags, stock levels and product master data, with a personal access token.\n\n## Authentication\n\nEvery request carries a **Bearer token** in the `Authorization` header:\n\n```\nAuthorization: Bearer bs_pat_xxxxxxxxxxxx\n```\n\nAccount owners create tokens under **Settings \u2192 API & KI-Zugriff**. A token is shown once, belongs to exactly one account and works only while its creator is still an owner of that account.\n\n## Rights\n\nEach token carries rights (`products.read`, `orders.read`, \u2026). A request without the right it needs is answered with `403`. Customer data \u2014 the customer endpoints and the customer and address block of an order \u2014 needs `customers.read`.\n\n## Rate limit\n\n120 requests per minute per account, shared by all tokens of the account. Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a `429` adds `Retry-After`.\n\n## Errors\n\nEvery error has the same shape: `{\"error\": \"\", \"message\": \"\"}`, a `422` adds `errors` with the messages per field.\n\n## Blocked accounts\n\nWhile an account has open usage to settle (Free plan above its limit, or unpaid orders), every endpoint except `GET \/me` answers `402` with `error: outbound_gated` and a `reason` (`free_hard_cap` or `unpaid_orders`). `GET \/me` reports the state in `outbound_gate`.\n\n## Money\n\nOrder and document amounts are integer **cents** in the order currency. Product prices are decimal strings in **euro** (`\"12.9900\"`), as stored." }, "servers": [ { "url": "https:\/\/billstack.app\/api\/v1", "description": "Billstack" } ], "tags": [ { "name": "Account" }, { "name": "Products" }, { "name": "Stock" }, { "name": "Orders" }, { "name": "Documents" }, { "name": "Customers" } ], "security": [ { "http": [] } ], "paths": { "\/me": { "get": { "operationId": "merchant-api.me", "description": "Who you are talking to: the account the token belongs to, the rights it\ncarries and when it expires. Needs no right \u2014 every valid token may call it.\n\n`outbound_gate` tells whether the account is blocked: while `gated` is\ntrue, every other endpoint answers `402 outbound_gated` until the open\nusage is settled in Billstack; `reason` is `free_hard_cap` or\n`unpaid_orders`. This endpoint itself always answers.", "summary": "The token and its account", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "token": { "type": "object", "description": "A chat app signed in via OAuth has no token row: its name stands\nin, id and expiry stay null.", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "expires_at" ] }, "scopes": { "type": "array", "items": {} }, "rate_limit_per_minute": { "type": "integer", "const": 120 }, "outbound_gate": { "type": "object", "properties": { "gated": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "gated", "reason" ] } }, "required": [ "account", "token", "scopes", "rate_limit_per_minute", "outbound_gate" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/customers": { "get": { "operationId": "merchant-api.customers.index", "description": "The account's customers with their newest billing and shipping address.\nSorted by `updated_at` ascending with the id as tiebreaker.", "summary": "List customers", "tags": [ "Customers" ], "parameters": [ { "name": "email", "in": "query", "description": "Only the customer with exactly this e-mail address (case-insensitive).", "schema": { "type": "string" }, "example": "jane@example.com" }, { "name": "updated_since", "in": "query", "description": "Only customers changed at or after this timestamp (ISO-8601, any offset).", "schema": { "type": "string" }, "example": "2026-10-23T10:00:00+02:00" }, { "name": "per_page", "in": "query", "description": "Items per page (1\u2013100).", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/customers\/{customer}": { "get": { "operationId": "merchant-api.customers.show", "description": "One customer in the same shape as the list.", "summary": "Get a customer", "tags": [ "Customers" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "customer_number": { "type": "integer" }, "customer_type": { "type": "string" }, "anonymized": { "type": "boolean" }, "company": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Marketplaces that withhold the buyer's address get a synthetic\nkey on the `.invalid` TLD \u2014 an identity key, never a contact\naddress: `email_is_placeholder` says which one this is." }, "email_is_placeholder": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "billing_address": { "type": [ "object", "null" ], "description": "The newest billing and shipping row, like the customer page.", "properties": { "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "address_line1": { "type": "string" }, "address_line2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "company", "address_line1", "address_line2", "postal_code", "city", "state", "country_code", "phone" ] }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "address_line1": { "type": "string" }, "address_line2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "company", "address_line1", "address_line2", "postal_code", "city", "state", "country_code", "phone" ] } }, "required": [ "id", "customer_number", "customer_type", "anonymized", "company", "first_name", "last_name", "email", "email_is_placeholder", "phone", "vat_id", "created_at", "updated_at", "billing_address", "shipping_address" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "customer_number": { "type": "integer" }, "customer_type": { "type": "string" }, "anonymized": { "type": "boolean" }, "company": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Marketplaces that withhold the buyer's address get a synthetic\nkey on the `.invalid` TLD \u2014 an identity key, never a contact\naddress: `email_is_placeholder` says which one this is." }, "email_is_placeholder": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "customer_number", "customer_type", "anonymized", "company", "first_name", "last_name", "email", "email_is_placeholder", "phone", "vat_id", "created_at", "updated_at" ] } ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No customer with this id exists in the token's account. An id of another account is a 404, never a 403.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/documents": { "get": { "operationId": "merchant-api.documents.index", "description": "Newest first by issue date; `sort=updated_at` is the polling cursor\n(oldest change first, id as tiebreaker). Amounts are cents of the order\ncurrency as stored on the document.", "summary": "List documents", "tags": [ "Documents" ], "parameters": [ { "name": "type", "in": "query", "description": "Only these types, comma-separated: invoice, cancellation, credit_note, quote, pro_forma_invoice.", "schema": { "type": "string" }, "example": "invoice,credit_note" }, { "name": "issued_from", "in": "query", "description": "Only documents issued on or after this day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "issued_to", "in": "query", "description": "Only documents issued on or before this day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" }, { "name": "order_id", "in": "query", "description": "Only the documents of this order.", "schema": { "type": "string", "format": "uuid" } }, { "name": "updated_since", "in": "query", "description": "Only documents changed at or after this timestamp (ISO-8601, any offset).", "schema": { "type": "string" }, "example": "2026-10-23T10:00:00+02:00" }, { "name": "sort", "in": "query", "description": "Sort: `issued_at` (newest first, default) or `updated_at` (oldest change first \u2014 the polling cursor).", "schema": { "type": "string", "default": "issued_at" }, "example": "updated_at" }, { "name": "per_page", "in": "query", "description": "Items per page (1\u2013100).", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/documents\/{invoice}": { "get": { "operationId": "merchant-api.documents.show", "description": "The metadata of one document plus the documents that point at it: its\ncancellation (`cancelled_by_document_ids`) and its credit notes\n(`credit_note_ids`).", "summary": "Get a document", "tags": [ "Documents" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "description": "One of 'invoice', 'cancellation', 'credit_note', 'quote' or\n'pro_forma_invoice'." }, "number": { "type": "string" }, "order_id": { "type": "string" }, "external_order_id": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "due_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ], "description": "Set when the document was cancelled (a Storno exists for it) or\nsuperseded (a newer pro-forma)." }, "currency": { "description": "Amounts in cents of the order currency, as stored on the document.", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "EUR" ] } ] }, "subtotal_net": { "type": "integer" }, "tax_total": { "type": "integer" }, "grand_total": { "type": "integer" }, "cancels_document_id": { "type": [ "string", "null" ], "description": "The chain: a cancellation names the document it cancels, a credit\nnote the invoice it credits." }, "credits_document_id": { "type": [ "string", "null" ] }, "return_id": { "type": [ "string", "null" ] }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the merchant's\nown file)." }, "sha256": { "type": [ "string", "null" ] }, "size_bytes": { "type": [ "integer", "null" ] }, "has_xml": { "type": "string" }, "pdf_url": { "type": "string" }, "xml_url": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "cancelled_by_document_ids": { "type": "array", "items": {} }, "credit_note_ids": { "type": "array", "items": {} } }, "required": [ "id", "type", "number", "order_id", "external_order_id", "issued_at", "due_at", "cancelled_at", "currency", "subtotal_net", "tax_total", "grand_total", "cancels_document_id", "credits_document_id", "return_id", "source", "sha256", "size_bytes", "has_xml", "pdf_url", "xml_url", "updated_at", "cancelled_by_document_ids", "credit_note_ids" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No document with this id exists in the token's account (another account's id is a 404, never a 403). Delivery notes are not served by this API.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/documents\/{invoice}\/pdf": { "get": { "operationId": "merchant-api.documents.pdf", "description": "Streams the document as `application\/pdf` (`Content-Disposition:\nattachment`), with the SHA-256 of the served bytes in `X-Document-Sha256`.\nA ZUGFeRD invoice carries its XML inside the PDF as well.", "summary": "Download the PDF", "tags": [ "Documents" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The PDF stream; the SHA-256 of the bytes in `X-Document-Sha256`.", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "409": { "description": "`error: document_not_rendered` \u2014 the document exists but its file has not been written yet (the PDF job is still queued). Retry later; a GET never renders.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No document with this id exists in the token's account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/documents\/{invoice}\/xml": { "get": { "operationId": "merchant-api.documents.xml", "description": "Streams the e-invoice XML of the document as `application\/xml`, with the\nSHA-256 of the served bytes in `X-Document-Sha256`. Only documents with\n`has_xml: true` have one.", "summary": "Download the ZUGFeRD XML", "tags": [ "Documents" ], "parameters": [ { "name": "invoice", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The XML stream; the SHA-256 of the bytes in `X-Document-Sha256`.", "content": { "application\/xml": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Transfer-Encoding": { "required": true, "schema": { "type": "string", "enum": [ "chunked" ] } } } }, "409": { "description": "`error: document_not_rendered` \u2014 the XML is announced but its file has not been written yet. Retry later; a GET never renders.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No document with this id exists in the token's account, or the document has no XML (`has_xml: false`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/orders": { "get": { "operationId": "merchant-api.orders.index", "description": "The account's orders with lines, totals in cents, tags, shipments and\ndocument references. The customer, the addresses, the buyer note and the\nline personalization are only filled for a token with `customers.read`\n(and never for an anonymized order) \u2014 otherwise they are `null`.\n\nNewest order first by default; the polling cursor is\n`?updated_since=\u2026&sort=updated_at` (oldest change first, id as\ntiebreaker).", "summary": "List orders", "tags": [ "Orders" ], "parameters": [ { "name": "status", "in": "query", "description": "Only these statuses, comma-separated: draft, confirmed, paid, in_fulfillment, shipped, completed, cancelled, merged.", "schema": { "type": "string" }, "example": "paid,shipped" }, { "name": "source", "in": "query", "description": "Only these sales channels, comma-separated: ebay, shopify, shopware, amazon, manual, etsy, kaufland, otto, temu, woocommerce, tiktok.", "schema": { "type": "string" }, "example": "ebay,shopify" }, { "name": "tag", "in": "query", "description": "Only orders carrying this own tag (case-insensitive).", "schema": { "type": "string" }, "example": "VIP" }, { "name": "created_from", "in": "query", "description": "Only orders placed on or after this day (order date, YYYY-MM-DD).", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "created_to", "in": "query", "description": "Only orders placed on or before this day (order date, YYYY-MM-DD).", "schema": { "type": "string", "format": "date" }, "example": "2026-10-31" }, { "name": "updated_since", "in": "query", "description": "Only orders changed at or after this timestamp (ISO-8601, any offset).", "schema": { "type": "string" }, "example": "2026-10-23T10:00:00+02:00" }, { "name": "sort", "in": "query", "description": "Sort: `order_date` (newest first, default) or `updated_at` (oldest change first \u2014 the polling cursor).", "schema": { "type": "string", "default": "order_date" }, "example": "updated_at" }, { "name": "per_page", "in": "query", "description": "Items per page (1\u2013100).", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/orders\/{order}": { "get": { "operationId": "merchant-api.orders.show", "description": "One order in the same shape as the list.", "summary": "Get an order", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "external_order_id": { "type": "string", "description": "The marketplace's order number (there is no `order_number` column)." }, "source": { "type": "string" }, "integration_id": { "type": [ "string", "null" ] }, "order_date": { "type": "string" }, "status": { "type": "string" }, "is_shipped": { "type": "boolean" }, "shipped_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "archived_at": { "type": [ "string", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "subtotal_net": { "type": "integer" }, "shipping_net": { "type": "integer" }, "shipping_gross": { "type": "integer" }, "tax_total": { "type": "integer" }, "grand_total": { "type": "integer" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "is_locked": { "type": "boolean", "description": "True for an order whose customer was anonymized: the record stays,\nits personal data are gone." }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "customer_number": { "type": "integer" }, "customer_type": { "type": "string" }, "anonymized": { "type": "boolean" }, "company": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Marketplaces that withhold the buyer's address get a synthetic\nkey on the `.invalid` TLD \u2014 an identity key, never a contact\naddress: `email_is_placeholder` says which one this is." }, "email_is_placeholder": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "billing_address": { "type": [ "object", "null" ], "description": "The newest billing and shipping row, like the customer page.", "properties": { "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "address_line1": { "type": "string" }, "address_line2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "company", "address_line1", "address_line2", "postal_code", "city", "state", "country_code", "phone" ] }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "address_line1": { "type": "string" }, "address_line2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "company", "address_line1", "address_line2", "postal_code", "city", "state", "country_code", "phone" ] } }, "required": [ "id", "customer_number", "customer_type", "anonymized", "company", "first_name", "last_name", "email", "email_is_placeholder", "phone", "vat_id", "created_at", "updated_at", "billing_address", "shipping_address" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "customer_number": { "type": "integer" }, "customer_type": { "type": "string" }, "anonymized": { "type": "boolean" }, "company": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "description": "Marketplaces that withhold the buyer's address get a synthetic\nkey on the `.invalid` TLD \u2014 an identity key, never a contact\naddress: `email_is_placeholder` says which one this is." }, "email_is_placeholder": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "vat_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "customer_number", "customer_type", "anonymized", "company", "first_name", "last_name", "email", "email_is_placeholder", "phone", "vat_id", "created_at", "updated_at" ] }, { "type": "null" } ] }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "address_line1": { "type": "string" }, "address_line2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "company", "address_line1", "address_line2", "postal_code", "city", "state", "country_code", "phone" ] }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "address_line1": { "type": "string" }, "address_line2": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "country_code": { "type": "string" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "company", "address_line1", "address_line2", "postal_code", "city", "state", "country_code", "phone" ] }, "buyer_note": { "type": [ "string", "null" ] }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "carrier": { "type": "string" }, "service_type": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] } }, "required": [ "id", "carrier", "service_type", "status", "tracking_number", "tracking_url", "shipped_at", "delivered_at" ] } }, "documents": { "type": "array", "description": "References only; the metadata and files live under \/documents.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "number": { "type": "string" }, "issued_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "number", "issued_at", "cancelled_at" ] } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "gtin": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "quantity": { "type": "integer" }, "discount_percent": { "type": "object" }, "tax_rate": { "type": "object" }, "unit_price_gross": { "type": "integer" }, "line_total_net": { "type": "integer" }, "tax_amount": { "type": "integer" }, "line_total_gross": { "type": "integer" }, "is_gift_card": { "type": "boolean", "description": "A sold multi-purpose voucher: a liability, never revenue." }, "shipped_quantity": { "type": "integer" }, "image_url": { "type": [ "string", "null" ] }, "personalization": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "file" ] }, "url": { "type": "string" } }, "required": [ "label", "value", "kind" ] } } }, "required": [ "id", "product_id", "sku", "gtin", "title", "quantity", "discount_percent", "tax_rate", "unit_price_gross", "line_total_net", "tax_amount", "line_total_gross", "is_gift_card", "shipped_quantity", "image_url", "personalization" ] } }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "description": "The polling cursor (`?updated_since=\u2026&sort=updated_at`)." } }, "required": [ "id", "external_order_id", "source", "integration_id", "order_date", "status", "is_shipped", "shipped_at", "paid_at", "completed_at", "cancelled_at", "archived_at", "payment_method", "currency", "subtotal_net", "shipping_net", "shipping_gross", "tax_total", "grand_total", "internal_tags", "is_locked", "customer", "billing_address", "shipping_address", "buyer_note", "shipments", "documents", "lines", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No order with this id exists in the token's account. An id of another account is a 404, never a 403.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/orders\/{order}\/tags": { "put": { "operationId": "merchant-api.orders.tags.replace", "description": "Sets the order's own tags to exactly the list sent (`null` or `[]`\nclears them). Tags are trimmed, duplicates dropped case-insensitively;\nat most 20 tags of 50 characters. Tags are internal metadata: allowed in\nevery status, they never reach a marketplace, fire no automation and do\nnot move the order's `updated_at`.", "summary": "Replace the tags of an order", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 50 } } }, "required": [ "tags" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "changed": { "type": "boolean" } }, "required": [ "id", "internal_tags", "changed" ] } }, "required": [ "data" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No order with this id exists in the token's account. An id of another account is a 404, never a 403.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "patch": { "operationId": "merchant-api.orders.tags.change", "description": "Removes the tags in `remove`, then adds the ones in `add`, both\ncase-insensitively \u2014 naming a tag on both sides keeps it. Quiet like\nthe replace: no automation, `updated_at` stays.", "summary": "Add and remove tags of an order", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "add": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 50 } }, "remove": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 50 } } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "changed": { "type": "boolean" } }, "required": [ "id", "internal_tags", "changed" ] } }, "required": [ "data" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No order with this id exists in the token's account. An id of another account is a 404, never a 403.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/products": { "get": { "operationId": "merchant-api.products.index", "description": "The account's catalogue with master data, prices (euro decimal strings),\nown tags, family and stock per warehouse. Archived articles are listed\ntoo, marked with `archived_at`, so an `updated_since` poller learns about\na deactivation.\n\nSorted by `updated_at` ascending with the id as tiebreaker \u2014 paging\nthrough a moving window never skips or repeats a row.", "summary": "List products", "tags": [ "Products" ], "parameters": [ { "name": "sku", "in": "query", "description": "Only the article with exactly this SKU.", "schema": { "type": "string" }, "example": "WIDGET-001" }, { "name": "tag", "in": "query", "description": "Only articles carrying this own tag (case-insensitive).", "schema": { "type": "string" }, "example": "Sale" }, { "name": "updated_since", "in": "query", "description": "Only articles changed at or after this timestamp (ISO-8601, any offset).", "schema": { "type": "string" }, "example": "2026-10-23T10:00:00+02:00" }, { "name": "sort", "in": "query", "description": "Sort field: `updated_at` (oldest change first, default) or `sku`.", "schema": { "type": "string", "default": "updated_at" }, "example": "updated_at" }, { "name": "per_page", "in": "query", "description": "Items per page (1\u2013100).", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/products\/{product}": { "get": { "operationId": "merchant-api.products.show", "description": "One article with everything the list shows plus the customs text\n(`export_description`).", "summary": "Get a product", "tags": [ "Products" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "`item`, `bundle`, `case` (carton of an item) or `variant_parent`\n(the container of a variant family, it carries no stock itself)." }, "currency": { "type": "string", "const": "EUR" }, "net_price": { "type": [ "object", "null" ] }, "gross_price": { "type": [ "object", "null" ] }, "net_purchase_price": { "type": [ "object", "null" ] }, "tax_rate": { "type": "object" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "variant_ids": { "type": "array", "description": "The variants of a `variant_parent`; empty for every other type.", "items": {} }, "stock": { "type": "array", "description": "One entry per warehouse the article has a stock row in.", "items": { "type": "object", "properties": { "warehouse_id": { "type": [ "string", "null" ] }, "on_hand": { "type": "integer" }, "reserved": { "type": "integer" }, "available": { "type": "integer" } }, "required": [ "warehouse_id", "on_hand", "reserved", "available" ] } } }, "required": [ "type", "currency", "net_price", "gross_price", "net_purchase_price", "tax_rate", "internal_tags", "variant_ids", "stock" ], "additionalProperties": {} } }, "required": [ "data" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No article with this id exists in the token's account. An id of another account is a 404, never a 403.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "patch": { "operationId": "merchant-api.products.update", "description": "Changes the master data of one article \u2014 only the fields sent, at least\none. A merchant edit like the product form: it ends the initial\nmaster-data phase, so no marketplace import fills these fields again.\nReturns the article in the shape of `GET \/products\/{id}`;\n`meta.changed` is false when every sent value was already stored (then\nnothing was written).\n\nSelling prices are rounded to whole cents, the purchase price is kept to\nfour decimal places. Sending only `net_price` or only `gross_price`\nderives the other at the article's `tax_rate`. A variant container\n(`type: variant_parent`) takes only `title` and `image_url`.", "summary": "Update a product", "tags": [ "Products" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "gross_weight_g": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9999999 }, "net_weight_g": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9999999 }, "length_cm": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999 }, "width_cm": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999 }, "height_cm": { "type": [ "number", "null" ], "minimum": 0, "maximum": 99999 }, "title": { "type": "string", "description": "Title of the article.", "examples": [ "Widget, blue" ] }, "gtin": { "type": "string", "description": "GTIN\/EAN or any other identifier, up to 50 characters, stored as sent (trimmed) \u2014 like the product form, the format is not checked here but by the sales channel that requires it. `null` or an empty string clears it.", "examples": [ "4006381333931" ] }, "net_price": { "type": "string", "description": "Net selling price in euro \u2014 a decimal string with a point or a JSON number; rounded to whole cents. Without `gross_price`, the gross price is derived.", "examples": [ "12.99" ] }, "gross_price": { "type": "string", "description": "Gross selling price in euro; rounded to whole cents. Without `net_price`, the net price is derived.", "examples": [ "15.46" ] }, "net_purchase_price": { "type": "string", "description": "Purchase price (net) in euro, up to four decimal places.", "examples": [ "4.2500" ] }, "image_url": { "type": "string", "format": "uri", "description": "URL of the main picture, `https` only; Billstack fetches a thumbnail from it.", "examples": [ "https:\/\/cdn.example.com\/widget.jpg" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "description": "`item`, `bundle`, `case` (carton of an item) or `variant_parent`\n(the container of a variant family, it carries no stock itself)." }, "currency": { "type": "string", "const": "EUR" }, "net_price": { "type": [ "object", "null" ] }, "gross_price": { "type": [ "object", "null" ] }, "net_purchase_price": { "type": [ "object", "null" ] }, "tax_rate": { "type": "object" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "variant_ids": { "type": "array", "description": "The variants of a `variant_parent`; empty for every other type.", "items": {} }, "stock": { "type": "array", "description": "One entry per warehouse the article has a stock row in.", "items": { "type": "object", "properties": { "warehouse_id": { "type": [ "string", "null" ] }, "on_hand": { "type": "integer" }, "reserved": { "type": "integer" }, "available": { "type": "integer" } }, "required": [ "warehouse_id", "on_hand", "reserved", "available" ] } } }, "required": [ "type", "currency", "net_price", "gross_price", "net_purchase_price", "tax_rate", "internal_tags", "variant_ids", "stock" ], "additionalProperties": {} }, "meta": { "type": "object", "properties": { "changed": { "type": "boolean" } }, "required": [ "changed" ] } }, "required": [ "data", "meta" ] } } } }, "409": { "description": "`error: product_archived` \u2014 the article is archived; restore it in Billstack first.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No article with this id exists in the token's account. An id of another account is a 404, never a 403.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/products\/{product}\/tags": { "put": { "operationId": "merchant-api.products.tags.replace", "description": "Sets the article's own tags to exactly the list sent (`null` or `[]`\nclears them). Tags are trimmed, duplicates dropped case-insensitively;\nat most 20 tags of 50 characters.", "summary": "Replace the tags of a product", "tags": [ "Products" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 50 } } }, "required": [ "tags" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "changed": { "type": "boolean" } }, "required": [ "id", "internal_tags", "changed" ] } }, "required": [ "data" ] } } } }, "409": { "description": "`error: product_archived` \u2014 the article is archived; restore it in Billstack first.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No article with this id exists in the token's account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "patch": { "operationId": "merchant-api.products.tags.change", "description": "Removes the tags in `remove`, then adds the ones in `add`, both\ncase-insensitively \u2014 naming a tag on both sides keeps it. Tags the\narticle does not carry are ignored on removal.", "summary": "Add and remove tags of a product", "tags": [ "Products" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "add": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 50 } }, "remove": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 50 } } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "internal_tags": { "type": "array", "items": { "type": "string" } }, "changed": { "type": "boolean" } }, "required": [ "id", "internal_tags", "changed" ] } }, "required": [ "data" ] } } } }, "409": { "description": "`error: product_archived` \u2014 the article is archived; restore it in Billstack first.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No article with this id exists in the token's account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/stock": { "get": { "operationId": "merchant-api.stock.index", "description": "One entry per article and warehouse: on hand, reserved by open orders,\nand available (on hand minus reserved). Rows of archived articles are left\nout. Sorted by `updated_at` ascending with the id as tiebreaker.", "summary": "List stock levels", "tags": [ "Stock" ], "parameters": [ { "name": "sku", "in": "query", "description": "Only the article with exactly this SKU.", "schema": { "type": "string" }, "example": "WIDGET-001" }, { "name": "warehouse_id", "in": "query", "description": "Only this warehouse.", "schema": { "type": "string", "format": "uuid" } }, { "name": "updated_since", "in": "query", "description": "Only stock rows changed at or after this timestamp (ISO-8601, any offset).", "schema": { "type": "string" }, "example": "2026-10-23T10:00:00+02:00" }, { "name": "per_page", "in": "query", "description": "Items per page (1\u2013100).", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "current_page", "last_page", "per_page", "total" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } }, "put": { "operationId": "merchant-api.stock.update", "description": "Absolute stock per article and warehouse (\"this is the count\"), up to 500\nitems per call, in one transaction: on hand becomes `quantity`, reserved\nstays as it is. Every change is booked as a stock correction in the\narticle's stock history (note `API: `) and its timeline, and\na \"stock below minimum\" automation fires as for a correction in the app;\nthe same value again books nothing (`status: unchanged`).\n\nA SKU the account has no live article for is reported in its item\n(`status: error`, `error: product_not_found`) and the rest is written. A\nbatch with an archived or unknown warehouse, a warehouse kept by a service\nprovider (fulfillment provider, Amazon FBA \u2014 its stock comes from there),\na variant container or a set, or the same SKU and warehouse twice is a\n`422` naming the position (`items.3.warehouse_id`); nothing is written.", "summary": "Set stock levels", "tags": [ "Stock" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 255 }, "warehouse_id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 0, "maximum": 9999999 } }, "required": [ "sku", "warehouse_id", "quantity" ] } } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "One result per item, in request order, plus the counts.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "warehouse_id": { "type": "string" }, "product_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "updated", "unchanged", "error" ] }, "on_hand": { "type": "integer" }, "error": { "type": "string", "const": "product_not_found" }, "message": { "type": "string" } }, "required": [ "sku", "warehouse_id", "product_id", "status" ] } }, "meta": { "type": "object", "properties": { "updated": { "type": "integer" }, "unchanged": { "type": "integer" }, "errors": { "type": "integer" } }, "required": [ "updated", "unchanged", "errors" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "Invalid parameters or body (`error: validation_failed`); `errors` lists the messages per field.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, malformed, unknown, revoked or expired token, a closed account, or a token whose creator is no longer an owner of the account.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "402": { "description": "`error: outbound_gated` \u2014 the account is blocked until its open usage is settled in Billstack; `reason` is `free_hard_cap` or `unpaid_orders`. `GET \/me` keeps answering and reports the state.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "free_hard_cap", "unpaid_orders" ] } }, "required": [ "error", "message", "reason" ] } } } }, "403": { "description": "The token does not hold the right this endpoint needs (`error: forbidden`).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "More than 120 requests per minute for this account (all its tokens share the limit). Wait for `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } } } }