{ "openapi": "3.1.0", "info": { "title": "Billstack", "version": "3.0.0", "description": "# Billstack Fulfillment API\n\nThe Fulfillment API allows third-party fulfillment providers to integrate with Billstack for order fulfillment, product catalog access, stock management, and return notifications.\n\n## Authentication\n\nAll endpoints require a **Bearer token** in the `Authorization` header:\n\n```\nAuthorization: Bearer sk_live_xxxxxxxxxxxx\n```\n\nTokens are generated in the Billstack settings under **Fulfillment > Providers**. Sandbox tokens use the `sk_test_` prefix.\n\n## Sandbox\n\nPartners get a dedicated **sandbox tenant** on this same host \u2014 there is no separate staging domain. A sandbox tenant holds no live merchant data, and its webhooks fire exactly like production ones.\n\nSandbox tokens carry the `sk_test_` prefix and only work inside a sandbox tenant; a `sk_live_` token is rejected there, and a `sk_test_` token is rejected everywhere else. The endpoints in the **Sandbox** group create test orders, advance them and reset the tenant's transactional data.\n\n## Rate Limiting\n\nRequests are rate-limited per provider (default: 60\/min). Rate limit headers are included in every response:\n- `X-RateLimit-Limit` \u2014 Maximum requests per minute\n- `X-RateLimit-Remaining` \u2014 Remaining requests in the current window\n\n## Permissions\n\nEach provider token has scoped permissions (e.g. `orders.read`, `stock.update`). Requests to endpoints without the required permission return `403 Forbidden`.\n\n## Documents\n\nInvoices, delivery notes and pro-forma invoices of a fulfillment order are available as PDF documents to tokens holding the `documents.read` permission. The order payload carries the document metadata (type, number, size, SHA-256); the document endpoint streams the PDF itself.\n\nFor a **third-country destination** the pro-forma invoice is issued automatically \u2014 on assignment, and again whenever the address or the lines change \u2014 with its own number range (`PF-`), rendered in English, and never as a payment document. A pro-forma the merchant uploaded always wins over a generated one and is marked `source: uploaded`.\n\nErrors on both document endpoints: `403` (token without `documents.read`), `404` (unknown type, another provider's order, nothing issued, or no pro-forma due) and `422` (`error: company_settings_incomplete` \u2014 the merchant's sender block is incomplete; `message` names the missing field)." }, "servers": [ { "url": "https:\/\/billstack.app\/api\/v1\/fulfillment", "description": "Billstack" } ], "tags": [ { "name": "Fulfillment Orders" }, { "name": "Fulfillment Documents" }, { "name": "Products" }, { "name": "Stock" }, { "name": "Returns" }, { "name": "Sandbox" } ], "security": [ { "http": [] } ], "paths": { "\/orders\/{fulfillmentOrderId}\/documents": { "get": { "operationId": "fulfillment.orders.documents.index", "description": "Returns the metadata of every document that exists for the fulfillment\norder right now \u2014 invoice, delivery note and pro-forma invoice. Documents\nthat can still be generated on demand (delivery note; pro-forma for a\nthird-country destination) are NOT listed until they exist: fetch them\nthrough `GET \/orders\/{id}\/documents\/{type}` and they are created.\n\nNever contains the PDF bytes. Download them from each entry's `url`, or\nverify an already-downloaded file against its `sha256`.\n\n**Pro-forma lifecycle.** Billstack issues the pro-forma itself:\nautomatically when the order is assigned to a provider and the parcel has\na third-country destination (an EU seller shipping outside the EU goods\narea \u2014 Northern Ireland counts as inside it), and again whenever the\naddress or the lines change. A pro-forma the merchant uploaded stays\nuntouched and always wins; `source` then says `uploaded`, so you can tell\nthe two apart.", "summary": "List an order's documents", "tags": [ "Fulfillment Documents" ], "parameters": [ { "name": "fulfillmentOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Metadata ONLY \u2014 never the bytes. Standard Webhooks caps a\npayload at ~20 KB and a PDF is two orders of magnitude past\nthat, so binary data is LINKED (`url`), exactly as Sendcloud\nand Shippo do it. `sha256` lets the consumer verify what it\ndownloaded without a second round trip.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "One of 'invoice', 'delivery_note' or 'pro_forma_invoice' \u2014\nthe API names, not the internal `invoices.type` values." }, "id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the\nmerchant's own file, which always wins over a generated one)." }, "content_type": { "type": "string", "const": "application\/pdf" }, "size_bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "type", "id", "number", "source", "content_type", "size_bytes", "sha256", "created_at", "url" ] } } }, "required": [ "data" ] } } } }, "403": { "description": "Your token does not hold the `documents.read` permission.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No fulfillment order with this id belongs to your provider. Another provider's order is a 404, never a 403, so a token holder cannot learn that the id exists.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/orders\/{fulfillmentOrderId}\/documents\/{type}": { "get": { "operationId": "fulfillment.orders.documents.show", "description": "Streams the document as `application\/pdf` (`Content-Disposition:\nattachment`), with the SHA-256 of the bytes in `X-Document-Sha256`.\n\n`type` is one of `invoice`, `delivery_note`, `pro_forma_invoice`.\n\nGenerated on demand where possible: a `delivery_note` is created and\nrendered if the order has none, and a `pro_forma_invoice` is created for a\nthird-country destination. An `invoice` is never created here \u2014 a \u00a714\ndocument is minted only by the merchant.\n\nAsk for JSON instead (`?include=content`, or `Accept: application\/json`)\nto receive the metadata plus the file Base64-encoded in `content_base64`.\nPrefer the binary stream: Base64 inflates the transfer by a third.\n\n**Pro-forma lifecycle.** Billstack issues the pro-forma itself:\nautomatically when the order is assigned to a provider and the parcel has\na third-country destination (an EU seller shipping outside the EU goods\narea \u2014 Northern Ireland counts as inside it), and again whenever the\naddress or the lines change. A pro-forma the merchant uploaded stays\nuntouched and always wins; `source` then says `uploaded`, so you can tell\nthe two apart.\n\nThe pro-forma carries its own number range (`PF-`), is rendered in\nEnglish, and is never a payment document \u2014 it exists for customs and says\nso on the sheet.", "summary": "Download an order document", "tags": [ "Fulfillment Documents" ], "parameters": [ { "name": "fulfillmentOrderId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Set to `content` to receive JSON with the Base64-encoded PDF instead of the binary stream.", "schema": { "type": "string" }, "example": "content" } ], "responses": { "200": { "description": "The document as a PDF stream \u2014 `Content-Disposition: attachment`, the SHA-256 of the bytes in `X-Document-Sha256`. With `?include=content` (or `Accept: application\/json`) the same 200 carries the JSON variant instead: the metadata plus the file in `content_base64`.", "content": { "application\/json": { "schema": { "type": "object" } }, "application\/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Your token does not hold the `documents.read` permission.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "Unknown type, order of another provider, no invoice issued, destination not a third-country one (no pro-forma due), or order cancelled (no delivery note \/ pro-forma for a cancelled order; the invoice stays fetchable).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "description": "`error: company_settings_incomplete` \u2014 the merchant has not completed the sender block in Settings \u2192 Company; `message` names the missing field. Ask the merchant to complete it, then retry.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "company_settings_incomplete" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/orders": { "get": { "operationId": "fulfillment.orders.index", "description": "Returns a paginated list of fulfillment orders assigned to the authenticated provider,\nincluding the associated order details, customer, addresses, and line items.\n\nThe polling backup for the webhook feed is\n`?updated_since=\u2026&status=pending,transmitted&sort=updated_at`: ascending by\n`updated_at` with the id as tiebreaker, so paging through a moving window\nnever skips or repeats a row.", "summary": "List fulfillment orders", "tags": [ "Fulfillment Orders" ], "parameters": [ { "name": "status", "in": "query", "description": "Filter by fulfillment order status. Comma-separated list for several.", "schema": { "type": "string" }, "example": "pending,transmitted" }, { "name": "updated_since", "in": "query", "description": "Only orders changed at or after this timestamp (ISO-8601).", "schema": { "type": "string" }, "example": "2026-09-08T10:00:00+02:00" }, { "name": "sort", "in": "query", "description": "Sort field: `created_at` (newest first, default) or `updated_at` (oldest first \u2014 the polling cursor).", "schema": { "type": "string", "default": "created_at" }, "example": "updated_at" }, { "name": "per_page", "in": "query", "description": "Number of items per page (max 100).", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "transmitted_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancellation_requested_at": { "type": [ "string", "null" ], "description": "The cancellation conversation, in the snapshot itself: a poller that\nonly ever reads `GET \/orders` sees an open request (and its answer)\nwithout having to keep the webhook it may have missed." }, "cancellation_rejected_at": { "type": [ "string", "null" ] }, "cancellation_rejection_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "description": "The polling cursor (`?updated_since=\u2026&sort=updated_at`) \u2014 a consumer\nhas to see the value it must send back." }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "order_date": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "grand_total": { "type": "integer" }, "payment_method": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "estimated_weight_g": { "type": "integer" }, "contains_dangerous_goods": { "type": "boolean", "description": "Routing hint: a parcel with any hazardous line needs a\ncarrier contract that covers it, and the 3PL decides that\nper shipment, not per line." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "shipping_address": { "type": [ "object", "null" ], "description": "Address columns are `address_line1`\/`address_line2` (the house\nnumber lives inside line1) \u2014 there is no street\/street_number\nsplit. `phone` and `state` ship along: 3PLs need them for the\ncarrier's delivery notification and for non-EU destinations.\nThere is no address e-mail column; the contact address stays\n`customer.email`.", "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" ] }, "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": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Kept from v1 so an existing consumer does not break: the flat\ncarrier\/service_type of the shipment row." }, "service_type": { "type": [ "string", "null" ] }, "shipping_net": { "type": "integer" }, "shipping_gross": { "type": "integer" }, "fulfillment_channel": { "type": [ "string", "null" ] }, "decided_by": { "type": "string" }, "requested": { "anyOf": [ { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ] }, "service_type": { "type": "string" }, "source": { "type": "string", "const": "shipping_rule" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "null" }, "service_type": { "type": "null" }, "source": { "type": "null" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "string" }, "service_type": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "shipment" } }, "required": [ "carrier", "service_type", "source" ] } ] } }, "required": [ "carrier", "service_type", "shipping_net", "shipping_gross", "fulfillment_channel", "decided_by", "requested" ] }, "customs": { "type": "object", "description": "Everything the sending country's customs office wants that is\nnot per line: which documents travel with the parcel, the\ndelivery term, the exporter's registrations and the declared\nvalue. `invoice_number` and `export_reason` keep their v2.0\nmeaning \u2014 an existing consumer needs no change.", "properties": { "invoice_number": { "type": [ "string", "null" ] }, "pro_forma_number": { "type": [ "string", "null" ] }, "export_reason": { "type": "string", "const": "sale" }, "incoterm": { "type": "string" }, "eori_number": { "type": [ "string", "null" ] }, "ioss_number": { "type": [ "string", "null" ] }, "seller_vat_id": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "goods_value_net": { "type": "integer" }, "shipping_net": { "type": "integer" }, "total_value_net": { "type": "string" }, "total_net_weight_g": { "type": [ "integer", "null" ] }, "is_third_country_destination": { "type": "boolean" }, "destination_country_code": { "type": [ "string", "null" ] }, "incomplete_lines": { "type": "integer" } }, "required": [ "invoice_number", "pro_forma_number", "export_reason", "incoterm", "eori_number", "ioss_number", "seller_vat_id", "currency", "goods_value_net", "shipping_net", "total_value_net", "total_net_weight_g", "is_third_country_destination", "destination_country_code", "incomplete_lines" ] }, "documents": { "type": "array", "description": "Metadata ONLY \u2014 never the bytes. Standard Webhooks caps a\npayload at ~20 KB and a PDF is two orders of magnitude past\nthat, so binary data is LINKED (`url`), exactly as Sendcloud\nand Shippo do it. `sha256` lets the consumer verify what it\ndownloaded without a second round trip.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "One of 'invoice', 'delivery_note' or 'pro_forma_invoice' \u2014\nthe API names, not the internal `invoices.type` values." }, "id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the\nmerchant's own file, which always wins over a generated one)." }, "content_type": { "type": "string", "const": "application\/pdf" }, "size_bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "type", "id", "number", "source", "content_type", "size_bytes", "sha256", "created_at", "url" ] } }, "documents_url": { "type": "string" }, "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" }, "unit_price_net": { "type": "integer" }, "tax_rate": { "type": "object" }, "unit_price_gross": { "type": "integer", "description": "Same rounding as WooCommerceService::netToGrossCents() \u2014 the one\nconvention this codebase derives a gross cent amount with." }, "line_total_net": { "type": "integer" }, "line_total_gross": { "type": "string", "description": "Never recomputed: both are stored columns, and a client-side\nderivation from grand_total drifts (CLAUDE.md)." }, "image_url": { "type": [ "string", "null" ] }, "gross_weight_g": { "type": [ "integer", "null" ] }, "net_weight_g": { "type": [ "integer", "null" ] }, "length_cm": { "type": [ "object", "null" ] }, "width_cm": { "type": [ "object", "null" ] }, "height_cm": { "type": [ "object", "null" ] }, "hs_code": { "type": [ "string", "null" ], "description": "Customs data for cross-border parcels. The product column is\n`tariff_code`; it is exposed under the customs-declaration\nname `hs_code` the carriers and 3PLs use." }, "country_of_origin": { "type": [ "string", "null" ] }, "export_description": { "type": [ "string", "null" ] }, "is_dangerous_goods": { "type": "string" }, "dangerous_goods": { "type": [ "array", "null" ], "items": {} }, "components": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "product_id": { "type": "string" }, "quantity": { "type": "string" } }, "required": [ "sku", "product_id", "quantity" ] } } }, "required": [ "id", "product_id", "sku", "gtin", "title", "quantity", "discount_percent", "unit_price_net", "tax_rate", "unit_price_gross", "line_total_net", "line_total_gross", "image_url", "gross_weight_g", "net_weight_g", "length_cm", "width_cm", "height_cm", "hs_code", "country_of_origin", "export_description", "is_dangerous_goods", "dangerous_goods", "components" ] } } }, "required": [ "id", "order_number", "order_date", "status", "currency", "grand_total", "payment_method", "paid_at", "estimated_weight_g", "contains_dangerous_goods", "customer", "shipping_address", "billing_address", "shipping", "customs", "documents", "documents_url", "lines" ] } }, "required": [ "id", "status", "external_reference", "tracking_number", "tracking_url", "carrier", "error_message", "notes", "transmitted_at", "accepted_at", "shipped_at", "completed_at", "cancelled_at", "cancellation_requested_at", "cancellation_rejected_at", "cancellation_rejection_reason", "created_at", "updated_at", "order" ] } }, "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": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/orders\/{fulfillmentOrderId}": { "get": { "operationId": "fulfillment.orders.show", "description": "Returns a single fulfillment order with full order details including product information on line items.", "summary": "Get a fulfillment order", "tags": [ "Fulfillment Orders" ], "parameters": [ { "name": "fulfillmentOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "transmitted_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancellation_requested_at": { "type": [ "string", "null" ], "description": "The cancellation conversation, in the snapshot itself: a poller that\nonly ever reads `GET \/orders` sees an open request (and its answer)\nwithout having to keep the webhook it may have missed." }, "cancellation_rejected_at": { "type": [ "string", "null" ] }, "cancellation_rejection_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "description": "The polling cursor (`?updated_since=\u2026&sort=updated_at`) \u2014 a consumer\nhas to see the value it must send back." }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "order_date": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "grand_total": { "type": "integer" }, "payment_method": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "estimated_weight_g": { "type": "integer" }, "contains_dangerous_goods": { "type": "boolean", "description": "Routing hint: a parcel with any hazardous line needs a\ncarrier contract that covers it, and the 3PL decides that\nper shipment, not per line." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "shipping_address": { "type": [ "object", "null" ], "description": "Address columns are `address_line1`\/`address_line2` (the house\nnumber lives inside line1) \u2014 there is no street\/street_number\nsplit. `phone` and `state` ship along: 3PLs need them for the\ncarrier's delivery notification and for non-EU destinations.\nThere is no address e-mail column; the contact address stays\n`customer.email`.", "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" ] }, "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": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Kept from v1 so an existing consumer does not break: the flat\ncarrier\/service_type of the shipment row." }, "service_type": { "type": [ "string", "null" ] }, "shipping_net": { "type": "integer" }, "shipping_gross": { "type": "integer" }, "fulfillment_channel": { "type": [ "string", "null" ] }, "decided_by": { "type": "string" }, "requested": { "anyOf": [ { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ] }, "service_type": { "type": "string" }, "source": { "type": "string", "const": "shipping_rule" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "null" }, "service_type": { "type": "null" }, "source": { "type": "null" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "string" }, "service_type": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "shipment" } }, "required": [ "carrier", "service_type", "source" ] } ] } }, "required": [ "carrier", "service_type", "shipping_net", "shipping_gross", "fulfillment_channel", "decided_by", "requested" ] }, "customs": { "type": "object", "description": "Everything the sending country's customs office wants that is\nnot per line: which documents travel with the parcel, the\ndelivery term, the exporter's registrations and the declared\nvalue. `invoice_number` and `export_reason` keep their v2.0\nmeaning \u2014 an existing consumer needs no change.", "properties": { "invoice_number": { "type": [ "string", "null" ] }, "pro_forma_number": { "type": [ "string", "null" ] }, "export_reason": { "type": "string", "const": "sale" }, "incoterm": { "type": "string" }, "eori_number": { "type": [ "string", "null" ] }, "ioss_number": { "type": [ "string", "null" ] }, "seller_vat_id": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "goods_value_net": { "type": "integer" }, "shipping_net": { "type": "integer" }, "total_value_net": { "type": "string" }, "total_net_weight_g": { "type": [ "integer", "null" ] }, "is_third_country_destination": { "type": "boolean" }, "destination_country_code": { "type": [ "string", "null" ] }, "incomplete_lines": { "type": "integer" } }, "required": [ "invoice_number", "pro_forma_number", "export_reason", "incoterm", "eori_number", "ioss_number", "seller_vat_id", "currency", "goods_value_net", "shipping_net", "total_value_net", "total_net_weight_g", "is_third_country_destination", "destination_country_code", "incomplete_lines" ] }, "documents": { "type": "array", "description": "Metadata ONLY \u2014 never the bytes. Standard Webhooks caps a\npayload at ~20 KB and a PDF is two orders of magnitude past\nthat, so binary data is LINKED (`url`), exactly as Sendcloud\nand Shippo do it. `sha256` lets the consumer verify what it\ndownloaded without a second round trip.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "One of 'invoice', 'delivery_note' or 'pro_forma_invoice' \u2014\nthe API names, not the internal `invoices.type` values." }, "id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the\nmerchant's own file, which always wins over a generated one)." }, "content_type": { "type": "string", "const": "application\/pdf" }, "size_bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "type", "id", "number", "source", "content_type", "size_bytes", "sha256", "created_at", "url" ] } }, "documents_url": { "type": "string" }, "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" }, "unit_price_net": { "type": "integer" }, "tax_rate": { "type": "object" }, "unit_price_gross": { "type": "integer", "description": "Same rounding as WooCommerceService::netToGrossCents() \u2014 the one\nconvention this codebase derives a gross cent amount with." }, "line_total_net": { "type": "integer" }, "line_total_gross": { "type": "string", "description": "Never recomputed: both are stored columns, and a client-side\nderivation from grand_total drifts (CLAUDE.md)." }, "image_url": { "type": [ "string", "null" ] }, "gross_weight_g": { "type": [ "integer", "null" ] }, "net_weight_g": { "type": [ "integer", "null" ] }, "length_cm": { "type": [ "object", "null" ] }, "width_cm": { "type": [ "object", "null" ] }, "height_cm": { "type": [ "object", "null" ] }, "hs_code": { "type": [ "string", "null" ], "description": "Customs data for cross-border parcels. The product column is\n`tariff_code`; it is exposed under the customs-declaration\nname `hs_code` the carriers and 3PLs use." }, "country_of_origin": { "type": [ "string", "null" ] }, "export_description": { "type": [ "string", "null" ] }, "is_dangerous_goods": { "type": "string" }, "dangerous_goods": { "type": [ "array", "null" ], "items": {} }, "components": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "product_id": { "type": "string" }, "quantity": { "type": "string" } }, "required": [ "sku", "product_id", "quantity" ] } } }, "required": [ "id", "product_id", "sku", "gtin", "title", "quantity", "discount_percent", "unit_price_net", "tax_rate", "unit_price_gross", "line_total_net", "line_total_gross", "image_url", "gross_weight_g", "net_weight_g", "length_cm", "width_cm", "height_cm", "hs_code", "country_of_origin", "export_description", "is_dangerous_goods", "dangerous_goods", "components" ] } } }, "required": [ "id", "order_number", "order_date", "status", "currency", "grand_total", "payment_method", "paid_at", "estimated_weight_g", "contains_dangerous_goods", "customer", "shipping_address", "billing_address", "shipping", "customs", "documents", "documents_url", "lines" ] } }, "required": [ "id", "status", "external_reference", "tracking_number", "tracking_url", "carrier", "error_message", "notes", "transmitted_at", "accepted_at", "shipped_at", "completed_at", "cancelled_at", "cancellation_requested_at", "cancellation_rejected_at", "cancellation_rejection_reason", "created_at", "updated_at", "order" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/orders\/{fulfillmentOrderId}\/status": { "patch": { "operationId": "fulfillment.orders.update-status", "description": "Transitions a fulfillment order to a new status. Only valid transitions are allowed\n(e.g. `transmitted` -> `accepted` -> `processing` -> `shipped` -> `completed`).\nProvide tracking information when shipping \u2014 either the flat `tracking_number`\nfields for a single parcel, or `packages[]` when the order was split across\nseveral parcels (each entry takes `tracking_number`, `carrier`, `tracking_url`).\nThe first parcel becomes the order's primary shipment; every further parcel is\nrecorded as its own shipment and pushed to the marketplace separately.", "summary": "Update fulfillment order status", "tags": [ "Fulfillment Orders" ], "parameters": [ { "name": "fulfillmentOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`cancelled` and `cancellation_rejected` are the two ANSWERS to a\nmerchant cancellation request \u2014 they are only legal from\n`cancellation_requested` (see below). \"We cannot fulfil this at\n all\" stays `error`.", "enum": [ "transmitted", "accepted", "processing", "shipped", "completed", "error", "cancelled", "cancellation_rejected" ] }, "reason": { "type": [ "string", "null" ], "maxLength": 1000 }, "external_reference": { "type": [ "string", "null" ], "maxLength": 255 }, "tracking_number": { "type": [ "string", "null" ], "description": "Required for \"shipped\": without a tracking number no marketplace\npush job is ever queued, the order would sit on sync \"pending\"\nforever \u2014 and a follow-up PATCH cannot heal it (Shipped \u2192 Shipped\nis no valid transition). Report shipped WITH its tracking \u2014 either\nas the flat field or as the first entry of `packages[]`.", "maxLength": 255 }, "tracking_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "carrier": { "type": [ "string", "null" ], "maxLength": 100 }, "packages": { "type": "array", "description": "Multi-package (v1): a 3PL that split the order across parcels reports\nthem all here. The FIRST parcel is the primary one and travels the\nunchanged single-shipment path; the rest become extra shipment rows,\neach with its own marketplace push.", "items": { "type": "object", "properties": { "tracking_number": { "type": "string", "maxLength": 255 }, "carrier": { "type": [ "string", "null" ], "maxLength": 100 }, "tracking_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 } }, "required": [ "tracking_number" ] }, "maxItems": 50 }, "error_message": { "type": [ "string", "null" ], "maxLength": 1000 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "transmitted_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancellation_requested_at": { "type": [ "string", "null" ], "description": "The cancellation conversation, in the snapshot itself: a poller that\nonly ever reads `GET \/orders` sees an open request (and its answer)\nwithout having to keep the webhook it may have missed." }, "cancellation_rejected_at": { "type": [ "string", "null" ] }, "cancellation_rejection_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "description": "The polling cursor (`?updated_since=\u2026&sort=updated_at`) \u2014 a consumer\nhas to see the value it must send back." }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "order_date": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "grand_total": { "type": "integer" }, "payment_method": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "estimated_weight_g": { "type": "integer" }, "contains_dangerous_goods": { "type": "boolean", "description": "Routing hint: a parcel with any hazardous line needs a\ncarrier contract that covers it, and the 3PL decides that\nper shipment, not per line." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "shipping_address": { "type": [ "object", "null" ], "description": "Address columns are `address_line1`\/`address_line2` (the house\nnumber lives inside line1) \u2014 there is no street\/street_number\nsplit. `phone` and `state` ship along: 3PLs need them for the\ncarrier's delivery notification and for non-EU destinations.\nThere is no address e-mail column; the contact address stays\n`customer.email`.", "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" ] }, "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": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Kept from v1 so an existing consumer does not break: the flat\ncarrier\/service_type of the shipment row." }, "service_type": { "type": [ "string", "null" ] }, "shipping_net": { "type": "integer" }, "shipping_gross": { "type": "integer" }, "fulfillment_channel": { "type": [ "string", "null" ] }, "decided_by": { "type": "string" }, "requested": { "anyOf": [ { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ] }, "service_type": { "type": "string" }, "source": { "type": "string", "const": "shipping_rule" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "null" }, "service_type": { "type": "null" }, "source": { "type": "null" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "string" }, "service_type": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "shipment" } }, "required": [ "carrier", "service_type", "source" ] } ] } }, "required": [ "carrier", "service_type", "shipping_net", "shipping_gross", "fulfillment_channel", "decided_by", "requested" ] }, "customs": { "type": "object", "description": "Everything the sending country's customs office wants that is\nnot per line: which documents travel with the parcel, the\ndelivery term, the exporter's registrations and the declared\nvalue. `invoice_number` and `export_reason` keep their v2.0\nmeaning \u2014 an existing consumer needs no change.", "properties": { "invoice_number": { "type": [ "string", "null" ] }, "pro_forma_number": { "type": [ "string", "null" ] }, "export_reason": { "type": "string", "const": "sale" }, "incoterm": { "type": "string" }, "eori_number": { "type": [ "string", "null" ] }, "ioss_number": { "type": [ "string", "null" ] }, "seller_vat_id": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "goods_value_net": { "type": "integer" }, "shipping_net": { "type": "integer" }, "total_value_net": { "type": "string" }, "total_net_weight_g": { "type": [ "integer", "null" ] }, "is_third_country_destination": { "type": "boolean" }, "destination_country_code": { "type": [ "string", "null" ] }, "incomplete_lines": { "type": "integer" } }, "required": [ "invoice_number", "pro_forma_number", "export_reason", "incoterm", "eori_number", "ioss_number", "seller_vat_id", "currency", "goods_value_net", "shipping_net", "total_value_net", "total_net_weight_g", "is_third_country_destination", "destination_country_code", "incomplete_lines" ] }, "documents": { "type": "array", "description": "Metadata ONLY \u2014 never the bytes. Standard Webhooks caps a\npayload at ~20 KB and a PDF is two orders of magnitude past\nthat, so binary data is LINKED (`url`), exactly as Sendcloud\nand Shippo do it. `sha256` lets the consumer verify what it\ndownloaded without a second round trip.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "One of 'invoice', 'delivery_note' or 'pro_forma_invoice' \u2014\nthe API names, not the internal `invoices.type` values." }, "id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the\nmerchant's own file, which always wins over a generated one)." }, "content_type": { "type": "string", "const": "application\/pdf" }, "size_bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "type", "id", "number", "source", "content_type", "size_bytes", "sha256", "created_at", "url" ] } }, "documents_url": { "type": "string" }, "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" }, "unit_price_net": { "type": "integer" }, "tax_rate": { "type": "object" }, "unit_price_gross": { "type": "integer", "description": "Same rounding as WooCommerceService::netToGrossCents() \u2014 the one\nconvention this codebase derives a gross cent amount with." }, "line_total_net": { "type": "integer" }, "line_total_gross": { "type": "string", "description": "Never recomputed: both are stored columns, and a client-side\nderivation from grand_total drifts (CLAUDE.md)." }, "image_url": { "type": [ "string", "null" ] }, "gross_weight_g": { "type": [ "integer", "null" ] }, "net_weight_g": { "type": [ "integer", "null" ] }, "length_cm": { "type": [ "object", "null" ] }, "width_cm": { "type": [ "object", "null" ] }, "height_cm": { "type": [ "object", "null" ] }, "hs_code": { "type": [ "string", "null" ], "description": "Customs data for cross-border parcels. The product column is\n`tariff_code`; it is exposed under the customs-declaration\nname `hs_code` the carriers and 3PLs use." }, "country_of_origin": { "type": [ "string", "null" ] }, "export_description": { "type": [ "string", "null" ] }, "is_dangerous_goods": { "type": "string" }, "dangerous_goods": { "type": [ "array", "null" ], "items": {} }, "components": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "product_id": { "type": "string" }, "quantity": { "type": "string" } }, "required": [ "sku", "product_id", "quantity" ] } } }, "required": [ "id", "product_id", "sku", "gtin", "title", "quantity", "discount_percent", "unit_price_net", "tax_rate", "unit_price_gross", "line_total_net", "line_total_gross", "image_url", "gross_weight_g", "net_weight_g", "length_cm", "width_cm", "height_cm", "hs_code", "country_of_origin", "export_description", "is_dangerous_goods", "dangerous_goods", "components" ] } } }, "required": [ "id", "order_number", "order_date", "status", "currency", "grand_total", "payment_method", "paid_at", "estimated_weight_g", "contains_dangerous_goods", "customer", "shipping_address", "billing_address", "shipping", "customs", "documents", "documents_url", "lines" ] } }, "required": [ "id", "status", "external_reference", "tracking_number", "tracking_url", "carrier", "error_message", "notes", "transmitted_at", "accepted_at", "shipped_at", "completed_at", "cancelled_at", "cancellation_requested_at", "cancellation_rejected_at", "cancellation_rejection_reason", "created_at", "updated_at", "order" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/products": { "get": { "operationId": "fulfillment.products.index", "description": "Returns a paginated product catalog for the provider's account.\nSupports filtering by exact SKU or free-text search across SKU, title, and GTIN.\n\nArchived (deactivated) SKUs are listed too, marked with `archived_at` \u2014 an\n`updated_since` poller has to learn about a deactivation, which a\nfiltered-out row could never tell it.", "summary": "List products", "tags": [ "Products" ], "parameters": [ { "name": "sku", "in": "query", "description": "Filter by exact SKU.", "schema": { "type": "string" }, "example": "WIDGET-001" }, { "name": "search", "in": "query", "description": "Search across SKU, title, and GTIN.", "schema": { "type": "string" }, "example": "widget" }, { "name": "updated_since", "in": "query", "description": "Only products changed at or after this timestamp (ISO-8601).", "schema": { "type": "string" }, "example": "2026-09-08T10:00:00+02:00" }, { "name": "dangerous_goods", "in": "query", "description": "Only (or only non-) dangerous goods.", "schema": { "type": "boolean" }, "example": true }, { "name": "sort", "in": "query", "description": "Sort field: `sku` (default) or `updated_at`.", "schema": { "type": "string", "default": "sku" }, "example": "updated_at" }, { "name": "direction", "in": "query", "description": "Sort direction: `asc` (default) or `desc`.", "schema": { "type": "string", "default": "asc" }, "example": "asc" }, { "name": "per_page", "in": "query", "description": "Number of items per page (max 100).", "schema": { "type": "integer", "default": 50 }, "example": 50 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "`items()`, not `through()`: the paginator would nest its own\nenvelope under `data` (`data.data`) \u2014 `GET \/orders` has always\nreturned a FLAT array and every endpoint of this API must agree.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "gtin": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "manufacturer": { "type": [ "string", "null" ] }, "parent_product_id": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "gross_weight_g": { "type": [ "integer", "null" ] }, "net_weight_g": { "type": [ "integer", "null" ] }, "length_cm": { "type": [ "object", "null" ] }, "width_cm": { "type": [ "object", "null" ] }, "height_cm": { "type": [ "object", "null" ] }, "country_of_origin": { "type": [ "string", "null" ] }, "tariff_code": { "type": [ "string", "null" ] }, "is_digital": { "type": "boolean" }, "is_dangerous_goods": { "type": "boolean" }, "dangerous_goods": { "type": [ "array", "null" ], "items": {} }, "updated_at": { "type": [ "string", "null" ] }, "archived_at": { "type": [ "string", "null" ] } }, "required": [ "id", "sku", "gtin", "title", "manufacturer", "parent_product_id", "image_url", "gross_weight_g", "net_weight_g", "length_cm", "width_cm", "height_cm", "country_of_origin", "tariff_code", "is_digital", "is_dangerous_goods", "dangerous_goods", "updated_at", "archived_at" ] } }, "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": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/products\/{productId}": { "get": { "operationId": "fulfillment.products.show", "description": "Returns full product details including physical dimensions, customs\ninformation and the dangerous goods declaration.", "summary": "Get a product", "tags": [ "Products" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} } }, "required": [ "data" ] } } } } } } }, "\/returns": { "post": { "operationId": "fulfillment.returns.store", "description": "Reports a return from the fulfillment warehouse. The notification is recorded\non the fulfillment order for processing. Items can be reported with their condition\n(good, damaged, defective).", "summary": "Create a return notification", "tags": [ "Returns" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "fulfillment_order_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 1000 }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 255 }, "quantity": { "type": "integer", "minimum": 1 }, "condition": { "type": "string", "enum": [ "good", "damaged", "defective" ] } }, "required": [ "sku", "quantity" ] }, "minItems": 1 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "fulfillment_order_id", "reason", "items" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "fulfillment_order_id": { "type": "string" }, "status": { "type": "string", "const": "received" }, "message": { "type": "string", "const": "Return notification has been recorded." } }, "required": [ "fulfillment_order_id", "status", "message" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sandbox\/orders": { "post": { "operationId": "fulfillment.sandbox.orders.store", "description": "**Sandbox only.** Requires an `sk_test_` token in a sandbox account; returns 403 elsewhere.\n\nCreates a real, paid order from a canned scenario and assigns it to the\ncalling provider \u2014 so the `order.assigned` webhook fires exactly as it\nwould in production. The response `data` block is byte-identical to\n`GET \/orders\/{id}`.\n\nScenarios: `domestic` (DE, 2 \u00d7 T-shirt), `export_ch` (CH, 3 \u00d7 mug \u2014 customs\ndata, tax rate 0), `dangerous_goods` (power bank UN 3480 + T-shirt), `kit`\n(2 \u00d7 bundle, exploded into 2 + 4 components), `multi_line` (three lines,\n10 % discount, mixed 7 % \/ 19 %).\n\nThere is NO idempotency key: every call creates a new order on purpose.\nA tenant may hold at most 500 orders \u2014 clear them with `POST \/sandbox\/reset`.", "summary": "Create a test order", "tags": [ "Sandbox" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "scenario": { "$ref": "#\/components\/schemas\/SandboxScenario" }, "order_number": { "type": [ "string", "null" ], "maxLength": 64 }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "transmitted_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancellation_requested_at": { "type": [ "string", "null" ], "description": "The cancellation conversation, in the snapshot itself: a poller that\nonly ever reads `GET \/orders` sees an open request (and its answer)\nwithout having to keep the webhook it may have missed." }, "cancellation_rejected_at": { "type": [ "string", "null" ] }, "cancellation_rejection_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "description": "The polling cursor (`?updated_since=\u2026&sort=updated_at`) \u2014 a consumer\nhas to see the value it must send back." }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "order_date": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "grand_total": { "type": "integer" }, "payment_method": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "estimated_weight_g": { "type": "integer" }, "contains_dangerous_goods": { "type": "boolean", "description": "Routing hint: a parcel with any hazardous line needs a\ncarrier contract that covers it, and the 3PL decides that\nper shipment, not per line." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "shipping_address": { "type": [ "object", "null" ], "description": "Address columns are `address_line1`\/`address_line2` (the house\nnumber lives inside line1) \u2014 there is no street\/street_number\nsplit. `phone` and `state` ship along: 3PLs need them for the\ncarrier's delivery notification and for non-EU destinations.\nThere is no address e-mail column; the contact address stays\n`customer.email`.", "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" ] }, "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": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Kept from v1 so an existing consumer does not break: the flat\ncarrier\/service_type of the shipment row." }, "service_type": { "type": [ "string", "null" ] }, "shipping_net": { "type": "integer" }, "shipping_gross": { "type": "integer" }, "fulfillment_channel": { "type": [ "string", "null" ] }, "decided_by": { "type": "string" }, "requested": { "anyOf": [ { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ] }, "service_type": { "type": "string" }, "source": { "type": "string", "const": "shipping_rule" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "null" }, "service_type": { "type": "null" }, "source": { "type": "null" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "string" }, "service_type": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "shipment" } }, "required": [ "carrier", "service_type", "source" ] } ] } }, "required": [ "carrier", "service_type", "shipping_net", "shipping_gross", "fulfillment_channel", "decided_by", "requested" ] }, "customs": { "type": "object", "description": "Everything the sending country's customs office wants that is\nnot per line: which documents travel with the parcel, the\ndelivery term, the exporter's registrations and the declared\nvalue. `invoice_number` and `export_reason` keep their v2.0\nmeaning \u2014 an existing consumer needs no change.", "properties": { "invoice_number": { "type": [ "string", "null" ] }, "pro_forma_number": { "type": [ "string", "null" ] }, "export_reason": { "type": "string", "const": "sale" }, "incoterm": { "type": "string" }, "eori_number": { "type": [ "string", "null" ] }, "ioss_number": { "type": [ "string", "null" ] }, "seller_vat_id": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "goods_value_net": { "type": "integer" }, "shipping_net": { "type": "integer" }, "total_value_net": { "type": "string" }, "total_net_weight_g": { "type": [ "integer", "null" ] }, "is_third_country_destination": { "type": "boolean" }, "destination_country_code": { "type": [ "string", "null" ] }, "incomplete_lines": { "type": "integer" } }, "required": [ "invoice_number", "pro_forma_number", "export_reason", "incoterm", "eori_number", "ioss_number", "seller_vat_id", "currency", "goods_value_net", "shipping_net", "total_value_net", "total_net_weight_g", "is_third_country_destination", "destination_country_code", "incomplete_lines" ] }, "documents": { "type": "array", "description": "Metadata ONLY \u2014 never the bytes. Standard Webhooks caps a\npayload at ~20 KB and a PDF is two orders of magnitude past\nthat, so binary data is LINKED (`url`), exactly as Sendcloud\nand Shippo do it. `sha256` lets the consumer verify what it\ndownloaded without a second round trip.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "One of 'invoice', 'delivery_note' or 'pro_forma_invoice' \u2014\nthe API names, not the internal `invoices.type` values." }, "id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the\nmerchant's own file, which always wins over a generated one)." }, "content_type": { "type": "string", "const": "application\/pdf" }, "size_bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "type", "id", "number", "source", "content_type", "size_bytes", "sha256", "created_at", "url" ] } }, "documents_url": { "type": "string" }, "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" }, "unit_price_net": { "type": "integer" }, "tax_rate": { "type": "object" }, "unit_price_gross": { "type": "integer", "description": "Same rounding as WooCommerceService::netToGrossCents() \u2014 the one\nconvention this codebase derives a gross cent amount with." }, "line_total_net": { "type": "integer" }, "line_total_gross": { "type": "string", "description": "Never recomputed: both are stored columns, and a client-side\nderivation from grand_total drifts (CLAUDE.md)." }, "image_url": { "type": [ "string", "null" ] }, "gross_weight_g": { "type": [ "integer", "null" ] }, "net_weight_g": { "type": [ "integer", "null" ] }, "length_cm": { "type": [ "object", "null" ] }, "width_cm": { "type": [ "object", "null" ] }, "height_cm": { "type": [ "object", "null" ] }, "hs_code": { "type": [ "string", "null" ], "description": "Customs data for cross-border parcels. The product column is\n`tariff_code`; it is exposed under the customs-declaration\nname `hs_code` the carriers and 3PLs use." }, "country_of_origin": { "type": [ "string", "null" ] }, "export_description": { "type": [ "string", "null" ] }, "is_dangerous_goods": { "type": "string" }, "dangerous_goods": { "type": [ "array", "null" ], "items": {} }, "components": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "product_id": { "type": "string" }, "quantity": { "type": "string" } }, "required": [ "sku", "product_id", "quantity" ] } } }, "required": [ "id", "product_id", "sku", "gtin", "title", "quantity", "discount_percent", "unit_price_net", "tax_rate", "unit_price_gross", "line_total_net", "line_total_gross", "image_url", "gross_weight_g", "net_weight_g", "length_cm", "width_cm", "height_cm", "hs_code", "country_of_origin", "export_description", "is_dangerous_goods", "dangerous_goods", "components" ] } } }, "required": [ "id", "order_number", "order_date", "status", "currency", "grand_total", "payment_method", "paid_at", "estimated_weight_g", "contains_dangerous_goods", "customer", "shipping_address", "billing_address", "shipping", "customs", "documents", "documents_url", "lines" ] } }, "required": [ "id", "status", "external_reference", "tracking_number", "tracking_url", "carrier", "error_message", "notes", "transmitted_at", "accepted_at", "shipped_at", "completed_at", "cancelled_at", "cancellation_requested_at", "cancellation_rejected_at", "cancellation_rejection_reason", "created_at", "updated_at", "order" ] }, "meta": { "type": "object", "properties": { "scenario": { "type": "string" }, "webhook_queued": { "type": "boolean" }, "webhook_delivery_id": { "type": [ "string", "null" ] } }, "required": [ "scenario", "webhook_queued", "webhook_delivery_id" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sandbox\/orders\/{fulfillmentOrderId}\/cancel": { "post": { "operationId": "fulfillment.sandbox.orders.cancel", "description": "**Sandbox only.** Requires an `sk_test_` token in a sandbox account; returns 403 elsewhere.\n\nDrives the merchant side of the cancellation state machine, so the partner\ncan see both answers it has to handle:\n\n- `pending` \/ `transmitted` \u2192 the order is cancelled outright and\n `order.cancelled` fires (`meta.mode = cancelled`).\n- `accepted` \/ `processing` \u2192 a cancellation REQUEST is opened and\n `order.cancellation_requested` fires (`meta.mode = cancellation_requested`);\n answer it with `PATCH \/orders\/{id}\/status` (`cancelled` or\n `cancellation_rejected`).\n\nAny other status answers 422 \u2014 a shipped order is not cancellable.", "summary": "Cancel a test order", "tags": [ "Sandbox" ], "parameters": [ { "name": "fulfillmentOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "transmitted_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancellation_requested_at": { "type": [ "string", "null" ], "description": "The cancellation conversation, in the snapshot itself: a poller that\nonly ever reads `GET \/orders` sees an open request (and its answer)\nwithout having to keep the webhook it may have missed." }, "cancellation_rejected_at": { "type": [ "string", "null" ] }, "cancellation_rejection_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "description": "The polling cursor (`?updated_since=\u2026&sort=updated_at`) \u2014 a consumer\nhas to see the value it must send back." }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "order_date": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "grand_total": { "type": "integer" }, "payment_method": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "estimated_weight_g": { "type": "integer" }, "contains_dangerous_goods": { "type": "boolean", "description": "Routing hint: a parcel with any hazardous line needs a\ncarrier contract that covers it, and the 3PL decides that\nper shipment, not per line." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "shipping_address": { "type": [ "object", "null" ], "description": "Address columns are `address_line1`\/`address_line2` (the house\nnumber lives inside line1) \u2014 there is no street\/street_number\nsplit. `phone` and `state` ship along: 3PLs need them for the\ncarrier's delivery notification and for non-EU destinations.\nThere is no address e-mail column; the contact address stays\n`customer.email`.", "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" ] }, "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": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Kept from v1 so an existing consumer does not break: the flat\ncarrier\/service_type of the shipment row." }, "service_type": { "type": [ "string", "null" ] }, "shipping_net": { "type": "integer" }, "shipping_gross": { "type": "integer" }, "fulfillment_channel": { "type": [ "string", "null" ] }, "decided_by": { "type": "string" }, "requested": { "anyOf": [ { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ] }, "service_type": { "type": "string" }, "source": { "type": "string", "const": "shipping_rule" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "null" }, "service_type": { "type": "null" }, "source": { "type": "null" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "string" }, "service_type": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "shipment" } }, "required": [ "carrier", "service_type", "source" ] } ] } }, "required": [ "carrier", "service_type", "shipping_net", "shipping_gross", "fulfillment_channel", "decided_by", "requested" ] }, "customs": { "type": "object", "description": "Everything the sending country's customs office wants that is\nnot per line: which documents travel with the parcel, the\ndelivery term, the exporter's registrations and the declared\nvalue. `invoice_number` and `export_reason` keep their v2.0\nmeaning \u2014 an existing consumer needs no change.", "properties": { "invoice_number": { "type": [ "string", "null" ] }, "pro_forma_number": { "type": [ "string", "null" ] }, "export_reason": { "type": "string", "const": "sale" }, "incoterm": { "type": "string" }, "eori_number": { "type": [ "string", "null" ] }, "ioss_number": { "type": [ "string", "null" ] }, "seller_vat_id": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "goods_value_net": { "type": "integer" }, "shipping_net": { "type": "integer" }, "total_value_net": { "type": "string" }, "total_net_weight_g": { "type": [ "integer", "null" ] }, "is_third_country_destination": { "type": "boolean" }, "destination_country_code": { "type": [ "string", "null" ] }, "incomplete_lines": { "type": "integer" } }, "required": [ "invoice_number", "pro_forma_number", "export_reason", "incoterm", "eori_number", "ioss_number", "seller_vat_id", "currency", "goods_value_net", "shipping_net", "total_value_net", "total_net_weight_g", "is_third_country_destination", "destination_country_code", "incomplete_lines" ] }, "documents": { "type": "array", "description": "Metadata ONLY \u2014 never the bytes. Standard Webhooks caps a\npayload at ~20 KB and a PDF is two orders of magnitude past\nthat, so binary data is LINKED (`url`), exactly as Sendcloud\nand Shippo do it. `sha256` lets the consumer verify what it\ndownloaded without a second round trip.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "One of 'invoice', 'delivery_note' or 'pro_forma_invoice' \u2014\nthe API names, not the internal `invoices.type` values." }, "id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the\nmerchant's own file, which always wins over a generated one)." }, "content_type": { "type": "string", "const": "application\/pdf" }, "size_bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "type", "id", "number", "source", "content_type", "size_bytes", "sha256", "created_at", "url" ] } }, "documents_url": { "type": "string" }, "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" }, "unit_price_net": { "type": "integer" }, "tax_rate": { "type": "object" }, "unit_price_gross": { "type": "integer", "description": "Same rounding as WooCommerceService::netToGrossCents() \u2014 the one\nconvention this codebase derives a gross cent amount with." }, "line_total_net": { "type": "integer" }, "line_total_gross": { "type": "string", "description": "Never recomputed: both are stored columns, and a client-side\nderivation from grand_total drifts (CLAUDE.md)." }, "image_url": { "type": [ "string", "null" ] }, "gross_weight_g": { "type": [ "integer", "null" ] }, "net_weight_g": { "type": [ "integer", "null" ] }, "length_cm": { "type": [ "object", "null" ] }, "width_cm": { "type": [ "object", "null" ] }, "height_cm": { "type": [ "object", "null" ] }, "hs_code": { "type": [ "string", "null" ], "description": "Customs data for cross-border parcels. The product column is\n`tariff_code`; it is exposed under the customs-declaration\nname `hs_code` the carriers and 3PLs use." }, "country_of_origin": { "type": [ "string", "null" ] }, "export_description": { "type": [ "string", "null" ] }, "is_dangerous_goods": { "type": "string" }, "dangerous_goods": { "type": [ "array", "null" ], "items": {} }, "components": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "product_id": { "type": "string" }, "quantity": { "type": "string" } }, "required": [ "sku", "product_id", "quantity" ] } } }, "required": [ "id", "product_id", "sku", "gtin", "title", "quantity", "discount_percent", "unit_price_net", "tax_rate", "unit_price_gross", "line_total_net", "line_total_gross", "image_url", "gross_weight_g", "net_weight_g", "length_cm", "width_cm", "height_cm", "hs_code", "country_of_origin", "export_description", "is_dangerous_goods", "dangerous_goods", "components" ] } } }, "required": [ "id", "order_number", "order_date", "status", "currency", "grand_total", "payment_method", "paid_at", "estimated_weight_g", "contains_dangerous_goods", "customer", "shipping_address", "billing_address", "shipping", "customs", "documents", "documents_url", "lines" ] } }, "required": [ "id", "status", "external_reference", "tracking_number", "tracking_url", "carrier", "error_message", "notes", "transmitted_at", "accepted_at", "shipped_at", "completed_at", "cancelled_at", "cancellation_requested_at", "cancellation_rejected_at", "cancellation_rejection_reason", "created_at", "updated_at", "order" ] }, "meta": { "type": "object", "properties": { "mode": { "type": "string", "const": "cancellation_requested" }, "webhook_queued": { "type": "boolean" }, "webhook_delivery_id": { "type": [ "string", "null" ] } }, "required": [ "mode", "webhook_queued", "webhook_delivery_id" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sandbox\/orders\/{fulfillmentOrderId}\/update": { "post": { "operationId": "fulfillment.sandbox.orders.update", "description": "**Sandbox only.** Requires an `sk_test_` token in a sandbox account; returns 403 elsewhere.\n\nSimulates the merchant editing an order that is still queued at the\nfulfiller, so `order.updated` fires with the fresh snapshot. Send a\npartial `shipping_address` object to steer the change, or no body at all\nto get a canned move to a different recipient in the same country.\n\nOnly `pending` and `transmitted` orders can change \u2014 from `accepted` on the\nmerchant UI blocks the edit too, and the endpoint answers 422.", "summary": "Change a test order's shipping address", "tags": [ "Sandbox" ], "parameters": [ { "name": "fulfillmentOrderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "shipping_address": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "company": { "type": [ "string", "null" ], "maxLength": 255 }, "address_line1": { "type": "string", "maxLength": 255 }, "address_line2": { "type": [ "string", "null" ], "maxLength": 255 }, "postal_code": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 100 }, "state": { "type": [ "string", "null" ], "maxLength": 100 }, "country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "phone": { "type": [ "string", "null" ], "maxLength": 50 } } } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "transmitted_at": { "type": [ "string", "null" ] }, "accepted_at": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "cancelled_at": { "type": [ "string", "null" ] }, "cancellation_requested_at": { "type": [ "string", "null" ], "description": "The cancellation conversation, in the snapshot itself: a poller that\nonly ever reads `GET \/orders` sees an open request (and its answer)\nwithout having to keep the webhook it may have missed." }, "cancellation_rejected_at": { "type": [ "string", "null" ] }, "cancellation_rejection_reason": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ], "description": "The polling cursor (`?updated_since=\u2026&sort=updated_at`) \u2014 a consumer\nhas to see the value it must send back." }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "order_number": { "type": "string" }, "order_date": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "grand_total": { "type": "integer" }, "payment_method": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "estimated_weight_g": { "type": "integer" }, "contains_dangerous_goods": { "type": "boolean", "description": "Routing hint: a parcel with any hazardous line needs a\ncarrier contract that covers it, and the 3PL decides that\nper shipment, not per line." }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] }, "shipping_address": { "type": [ "object", "null" ], "description": "Address columns are `address_line1`\/`address_line2` (the house\nnumber lives inside line1) \u2014 there is no street\/street_number\nsplit. `phone` and `state` ship along: 3PLs need them for the\ncarrier's delivery notification and for non-EU destinations.\nThere is no address e-mail column; the contact address stays\n`customer.email`.", "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" ] }, "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": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Kept from v1 so an existing consumer does not break: the flat\ncarrier\/service_type of the shipment row." }, "service_type": { "type": [ "string", "null" ] }, "shipping_net": { "type": "integer" }, "shipping_gross": { "type": "integer" }, "fulfillment_channel": { "type": [ "string", "null" ] }, "decided_by": { "type": "string" }, "requested": { "anyOf": [ { "type": "object", "properties": { "carrier": { "type": [ "string", "null" ] }, "service_type": { "type": "string" }, "source": { "type": "string", "const": "shipping_rule" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "null" }, "service_type": { "type": "null" }, "source": { "type": "null" } }, "required": [ "carrier", "service_type", "source" ] }, { "type": "object", "properties": { "carrier": { "type": "string" }, "service_type": { "type": [ "string", "null" ] }, "source": { "type": "string", "const": "shipment" } }, "required": [ "carrier", "service_type", "source" ] } ] } }, "required": [ "carrier", "service_type", "shipping_net", "shipping_gross", "fulfillment_channel", "decided_by", "requested" ] }, "customs": { "type": "object", "description": "Everything the sending country's customs office wants that is\nnot per line: which documents travel with the parcel, the\ndelivery term, the exporter's registrations and the declared\nvalue. `invoice_number` and `export_reason` keep their v2.0\nmeaning \u2014 an existing consumer needs no change.", "properties": { "invoice_number": { "type": [ "string", "null" ] }, "pro_forma_number": { "type": [ "string", "null" ] }, "export_reason": { "type": "string", "const": "sale" }, "incoterm": { "type": "string" }, "eori_number": { "type": [ "string", "null" ] }, "ioss_number": { "type": [ "string", "null" ] }, "seller_vat_id": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "goods_value_net": { "type": "integer" }, "shipping_net": { "type": "integer" }, "total_value_net": { "type": "string" }, "total_net_weight_g": { "type": [ "integer", "null" ] }, "is_third_country_destination": { "type": "boolean" }, "destination_country_code": { "type": [ "string", "null" ] }, "incomplete_lines": { "type": "integer" } }, "required": [ "invoice_number", "pro_forma_number", "export_reason", "incoterm", "eori_number", "ioss_number", "seller_vat_id", "currency", "goods_value_net", "shipping_net", "total_value_net", "total_net_weight_g", "is_third_country_destination", "destination_country_code", "incomplete_lines" ] }, "documents": { "type": "array", "description": "Metadata ONLY \u2014 never the bytes. Standard Webhooks caps a\npayload at ~20 KB and a PDF is two orders of magnitude past\nthat, so binary data is LINKED (`url`), exactly as Sendcloud\nand Shippo do it. `sha256` lets the consumer verify what it\ndownloaded without a second round trip.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "One of 'invoice', 'delivery_note' or 'pro_forma_invoice' \u2014\nthe API names, not the internal `invoices.type` values." }, "id": { "type": "string" }, "number": { "type": "string" }, "source": { "type": "string", "description": "'generated' (Billstack rendered it) or 'uploaded' (the\nmerchant's own file, which always wins over a generated one)." }, "content_type": { "type": "string", "const": "application\/pdf" }, "size_bytes": { "type": [ "integer", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "url": { "type": "string" } }, "required": [ "type", "id", "number", "source", "content_type", "size_bytes", "sha256", "created_at", "url" ] } }, "documents_url": { "type": "string" }, "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" }, "unit_price_net": { "type": "integer" }, "tax_rate": { "type": "object" }, "unit_price_gross": { "type": "integer", "description": "Same rounding as WooCommerceService::netToGrossCents() \u2014 the one\nconvention this codebase derives a gross cent amount with." }, "line_total_net": { "type": "integer" }, "line_total_gross": { "type": "string", "description": "Never recomputed: both are stored columns, and a client-side\nderivation from grand_total drifts (CLAUDE.md)." }, "image_url": { "type": [ "string", "null" ] }, "gross_weight_g": { "type": [ "integer", "null" ] }, "net_weight_g": { "type": [ "integer", "null" ] }, "length_cm": { "type": [ "object", "null" ] }, "width_cm": { "type": [ "object", "null" ] }, "height_cm": { "type": [ "object", "null" ] }, "hs_code": { "type": [ "string", "null" ], "description": "Customs data for cross-border parcels. The product column is\n`tariff_code`; it is exposed under the customs-declaration\nname `hs_code` the carriers and 3PLs use." }, "country_of_origin": { "type": [ "string", "null" ] }, "export_description": { "type": [ "string", "null" ] }, "is_dangerous_goods": { "type": "string" }, "dangerous_goods": { "type": [ "array", "null" ], "items": {} }, "components": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "product_id": { "type": "string" }, "quantity": { "type": "string" } }, "required": [ "sku", "product_id", "quantity" ] } } }, "required": [ "id", "product_id", "sku", "gtin", "title", "quantity", "discount_percent", "unit_price_net", "tax_rate", "unit_price_gross", "line_total_net", "line_total_gross", "image_url", "gross_weight_g", "net_weight_g", "length_cm", "width_cm", "height_cm", "hs_code", "country_of_origin", "export_description", "is_dangerous_goods", "dangerous_goods", "components" ] } } }, "required": [ "id", "order_number", "order_date", "status", "currency", "grand_total", "payment_method", "paid_at", "estimated_weight_g", "contains_dangerous_goods", "customer", "shipping_address", "billing_address", "shipping", "customs", "documents", "documents_url", "lines" ] } }, "required": [ "id", "status", "external_reference", "tracking_number", "tracking_url", "carrier", "error_message", "notes", "transmitted_at", "accepted_at", "shipped_at", "completed_at", "cancelled_at", "cancellation_requested_at", "cancellation_rejected_at", "cancellation_rejection_reason", "created_at", "updated_at", "order" ] }, "meta": { "type": "object", "properties": { "webhook_queued": { "type": "boolean" }, "webhook_delivery_id": { "type": [ "string", "null" ] } }, "required": [ "webhook_queued", "webhook_delivery_id" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/sandbox\/reset": { "post": { "operationId": "fulfillment.sandbox.reset", "description": "**Sandbox only.** Requires an `sk_test_` token in a sandbox account; returns 403 elsewhere.\n\nDeletes every test ORDER (with its lines, events, fulfillment orders,\nshipments, invoices and returns), the webhook delivery log, the accounting\nrows those orders posted and the test customers.\n\nKEPT: this provider (token and webhook secret survive a reset), rules,\nproducts and their components, warehouses, workflows and the API request\nlog. Runs synchronously \u2014 the next call is usually \"create an order\", and\nan async wipe would race it. A reset already in flight answers 409.", "summary": "Wipe the sandbox tenant", "tags": [ "Sandbox" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "purged" }, "deleted": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "status", "deleted" ] } } } }, "409": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "purge_in_progress" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "\/stock": { "get": { "operationId": "fulfillment.stock.index", "description": "Returns paginated inventory levels for the provider's linked warehouse.\nEach entry includes quantity, reserved, and available counts.", "summary": "List stock levels", "tags": [ "Stock" ], "parameters": [ { "name": "sku", "in": "query", "description": "Filter by exact product SKU.", "schema": { "type": "string" }, "example": "WIDGET-001" }, { "name": "per_page", "in": "query", "description": "Number of items per page (max 100).", "schema": { "type": "integer", "default": 50 }, "example": 50 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "`items()`, not `through()`: the paginator would nest its own\nenvelope under `data` (`data.data`) \u2014 `GET \/orders` has always\nreturned a FLAT array and every endpoint of this API must agree.", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "reserved": { "type": "integer" }, "available": { "type": "integer" } }, "required": [ "product_id", "sku", "title", "quantity", "reserved", "available" ] } }, "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": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "No warehouse linked" }, "message": { "type": "string", "const": "This fulfillment provider has no warehouse assigned. Please configure a warehouse in settings." } }, "required": [ "error", "message" ] } } } } } }, "put": { "operationId": "fulfillment.stock.update", "description": "Batch-update inventory quantities by SKU. Accepts up to 500 items per request.\nUnknown SKUs are reported as errors in the response without failing the entire batch.", "summary": "Update 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 }, "quantity": { "type": "integer", "minimum": 0 } }, "required": [ "sku", "quantity" ] }, "minItems": 1, "maxItems": 500 } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "SandboxScenario": { "type": "string", "description": "The canned test orders a fulfillment partner can create in a sandbox tenant (`POST \/api\/v1\/fulfillment\/sandbox\/orders`). Each scenario pins ONE characteristic a fulfiller has to handle, so the partner can drive their integration through every branch without waiting for a real merchant to produce the case: - domestic DE destination, 2 \u00d7 T-shirt \u2014 the plain happy path. - export_ch CH destination, 3 \u00d7 mug \u2014 customs data, tax rate 0 (third-country export), pro-forma invoice. - dangerous_goods power bank + T-shirt \u2014 UN 3480 Li-Ion, standalone cell. - kit 2 \u00d7 starter kit \u2014 a bundle that explodes into components. - multi_line three lines, 10 % discount, mixed 7 % \/ 19 % tax rates. The labels are English on purpose: they are part of the public API contract and appear in the partner guide, never in the merchant UI.\n", "enum": [ "domestic", "export_ch", "dangerous_goods", "kit", "multi_line" ], "title": "SandboxScenario" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }