{ "openapi": "3.1.0", "info": { "title": "Click2Drop Store API", "version": "1.0.0", "description": "Your own software works with the Click2Drop catalogue directly: read products, stock and prices, place and follow orders, and hear about changes through webhooks or the event feed. Keys are issued in the client panel, under **Stores** \u2192 your API store \u2192 **API** \u2192 **Keys**.\n\nBase URL: `https://dev-v2.click2drop.eu/api/v1`\n\n## Authentication\n\nEvery request carries a store key as a bearer token:\n\n```\nAuthorization: Bearer ds_live_xxxxxxxx_\u2026\nAccept: application/json\n```\n\nA key is shown once, when it is created, and can be replaced or revoked at any time. An expired key no longer counts against the store's number of keys. A key carries **scopes**; every operation in this reference names the one it needs (**Scope:** at the top):\n\n| Scope | Allows |\n|---|---|\n| `catalog.read` | products, stock, prices, categories, countries, delivery methods, pickup points, checkout rates |\n| `orders.read` | orders, tracking, documents, returns, the inbox, the check before payment (`POST /orders/validate`) |\n| `orders.write` | quoting, placing, paying and cancelling orders; announcing and cancelling returns; retrying and rejecting inbox entries |\n| `webhooks.manage` | webhook endpoints, their secrets and deliveries |\n\nThe event feed (`GET /events`) needs `orders.read` or `catalog.read`, and each key hears only what it may read: `order.*` with `orders.read`; `product.*`, `price.updated`, `stock.updated` and `delivery.updated` with `catalog.read`; `store.paused` and `store.resumed` with either. A webhook endpoint follows the same rule: a key subscribes only to events it may read.\n\n| Answer | When |\n|---|---|\n| **401** `unauthenticated` | the key is missing, unknown, revoked or expired |\n| **410** `store-deleted` | the store behind the key was deleted \u2014 the key will never work again |\n| **423** `store-paused` | the store is paused |\n| **403** `insufficient-scope` | the key lacks the scope |\n| **403** `client-inactive`, `client-not-verified` | the account is not active, or not verified yet |\n| **403** `client-area-closed` | the platform does not take this account's orders yet: placing, paying, cancelling, returns and the inbox's retry and reject are refused; reading, quoting and the checks keep working |\n| **503** `maintenance` | the platform is under maintenance; retry after `Retry-After`. A shop's checkout stays open \u2014 `POST /checkout/rates`, `GET /delivery/pickup-points`, `POST /orders/validate` \u2014 so shops keep selling; their orders wait in the inbox and are placed when the works end |\n\n## Paging\n\nThese lists are keyset-paged and answer `data`, `next_cursor` and `has_more`: `/products`, `/stock`, `/prices`, `/orders`, `/inbox`, `/events`, `/webhooks/{id}/deliveries` (newest first). Pass `next_cursor` back as `cursor` to read on; on the last page it is null \u2014 except in `/events`, whose last page still carries it (keep it, and ask again later for what is new). `has_more` says whether another page follows right away. The other lists (categories, countries, delivery methods, pickup points, an order's documents, tracking and returns, webhook endpoints) are short and answer `data` only.\n\n`updated_since` (ISO 8601) narrows two lists to what changed:\n\n- `/orders` \u2014 the order itself, or any of its shipments, parcels, tracking events, documents or returns;\n- `/products` \u2014 the product's content, sell price or stock, or its place in the store (selected, paused). Our price for you (`purchase_price`) is not part of it: read `/prices` for those. Further back than events are kept (30 days unless the platform says otherwise) it narrows nothing \u2014 the whole catalogue comes. A product that leaves the catalogue is no longer listed \u2014 the event feed announces it as `product.removed`.\n\n```\nGET /products?limit=100\nGET /products?cursor=\nGET /orders?updated_since=2026-09-01T00:00:00Z\n```\n\n## Money\n\nAmounts are strings. Prices of products and delivery come as `{\"amount\": \"19.99\", \"currency\": \"EUR\"}`: a product's `sell_price` and the checkout's rates with two decimals, purchase prices and the delivery offer's figures with up to six. Purchase prices are in your account's currency; sell prices and the delivery offer in the store's. An order's and a quote's totals are plain strings in the one `currency` named beside them. Amounts you send (`total`, `cod_amount`, `recipient_price`, `shipment_totals`, `shipment_shipping`) are plain decimals with at most two places \u2014 `19.99` or `\"19.99\"`; `\"1e3\"`, `\"1,5\"` or `19.999` is a validation error. `cod_amount` is in the order's `currency` when you send one \u2014 we convert it at today's rate to the currency the courier collects in, and refuse cash on delivery (`cod_unavailable`) when no rate exists; without `currency` it is taken as already in the courier's currency.\n\n## Delivery\n\n`GET /delivery` lists the delivery methods the store offers its customers and what it charges for each: per destination country, weight brackets (kg \u2192 price) and a free-shipping threshold, in the store currency \u2014 the same shape as a weight-based shipping rate in Shopify or WooCommerce. Both ends of a bracket are inclusive; a weight exactly on a boundary takes the lower bracket. In `POST /checkout/rates` a bracket prices one parcel: a shipment packed into several parcels pays each parcel's bracket, summed \u2014 except a price the client typed for the method (simple pricing), which is one price for the shipment however it is packed. In simple pricing the client types one price per method; in advanced pricing the brackets are the platform tariff plus the client's markup and follow the tariff by themselves. A country with no price set yet is listed with empty `brackets`: the method still ships there, but there is no price to show the buyer. `GET /countries` lists the countries the store's methods reach.\n\nShow those in your shop; when placing an order, pass the chosen method's `id` in `couriers` (quote shipment id \u2192 method id). `POST /orders/quote` and a placement only use methods the store offers. Changes reach you as `delivery.updated`. A method whose `delivery_kind` is `pickup_point` goes to a locker or parcel shop: search the platform's directory with `GET /delivery/pickup-points` (nearest to the buyer first), then name the chosen point in `pickup_points` when placing (the recipient's own address is still required: it is who the courier notifies, and the parcel itself goes to the point). Such a method is never chosen for you: an order that names no courier gets the cheapest door courier.\n\n`POST /checkout/rates` prices a live cart for a checkout; its answer may lag the stock by a few minutes. `POST /orders/validate` judges the full order against live stock right before the buyer pays.\n\n## Placing an order\n\nSend the recipient and the lines by SKU. Your own reference goes in `external_reference` or in an `Idempotency-Key` header (at most 120 characters; it may contain `/`) \u2014 the same reference sent again returns the original result instead of creating another order.\n\n- **201** \u2014 placed; `order` holds it. Whenever the order is placed but not paid \u2014 the payment refused, or a card waiting for 3-D Secure \u2014 `payment_error` says why and the order waits for `POST /orders/{number}/pay` (for 3-D Secure it answers 202 with the address to send the customer to). Paying an order already paid answers 200 with the order, so a repeated call is safe.\n- **202** \u2014 waiting in the store's inbox, `status` `held` with a `hold_reason`, or `received` while it is being placed. Fix the cause and `POST /inbox/{reference}/retry` (or retry it in the client panel), or reject it.\n- The same reference sent again answers as its entry stands now: **200** when it was placed, **202** while it still waits.\n\nThe hold reasons: `unmapped_sku`, `not_selected`, `no_stock`, `country_not_served`, `cod_unavailable`, `recipient_invalid`, `pickup_point_invalid`, `no_door_courier`, `payment_failed`, `payment_lapsed`, `verification_required`, `manual_review`, `store_paused`, `split_changed`, `courier_unavailable`, `no_courier`, `other`. The same words come back as `reason` from `POST /orders/quote` and `POST /orders/validate` (422) \u2014 a quote and a check refuse exactly what the placement would hold, and price exactly what it would charge (couriers, pickup points, cash on delivery with its fee). The stock and the payment card are judged once more when the order arrives. A store that approves orders by hand still answers a check with `ok`: the order arrives and waits for that approval (`manual_review`).\n\nCancelling an order that is already cancelled answers 200, so a repeated call is safe. Paying or cancelling while another payment or cancellation of the same order is running answers **409** `order-busy`: read the order, then retry. An inbox entry keeps `placed` once an order was made; the order's own `state` says whether it was cancelled since.\n\n## Errors\n\nEvery error is an RFC 9457 problem-details document (`application/problem+json`):\n\n```json\n{\n \"type\": \"https://dev-v2.click2drop.eu/docs/api/errors/order-no-stock\",\n \"title\": \"Not enough stock\",\n \"status\": 422,\n \"detail\": \"\u2026\",\n \"reason\": \"no_stock\",\n \"request_id\": \"\u2026\"\n}\n```\n\nSwitch on the **slug** \u2014 the last segment of `type` \u2014 never on the title or the detail. Every slug, with when it comes, is listed on the [errors page](https://dev-v2.click2drop.eu/docs/api/errors); a `type` URL opens its entry there. Validation errors carry `errors` per field. Every answer \u2014 success or error \u2014 carries an `X-Request-Id` header; quote it (or `request_id`) when you write to support.\n\n## Events: webhooks and the feed\n\nThe same events reach you two ways: pushed to your webhook endpoints, or read from `GET /events`. Every event is a JSON envelope:\n\n```json\n{ \"id\": 123, \"type\": \"order.shipped\", \"created_at\": \"\u2026\", \"store_id\": 7, \"data\": { \u2026 } }\n```\n\n`id` identifies the event. A webhook retried after a lost answer keeps its `X-DS-Delivery-Id` \u2014 deduplicate deliveries on that. The same event `id` may also come again **with a newer state** (the feed lists an event once more when its subject changed after you read it; an endpoint switched back on is sent what it missed): treat it as an update, never drop it as a duplicate. An event says WHAT changed; its `data` is the thing **as it is when the event is delivered or read** \u2014 not a snapshot of the moment it happened. Read twice, the same event may show a later state; that is by design. Order events carry the order summary (`GET /orders` shape); inbox events (`order.held`, and `order.rejected` when an entry is rejected in the client panel \u2014 rejecting through the API sends none) the inbox entry (`GET /inbox/{reference}` shape); catalogue events the product as `GET /products/{sku}` shows it. Events: `order.placed`, `order.held`, `order.rejected`, `order.paid`, `order.shipped`, `order.tracking_updated`, `order.delivered`, `order.cancelled`, `order.document_added`, `order.return_announced`, `order.return_updated`, `order.refunded`, `product.updated`, `product.removed`, `price.updated`, `stock.updated`, `delivery.updated`, `store.paused`, `store.resumed`.\n\nEvery webhook is documented under **Webhooks** in the sidebar, next to the endpoints: when it fires, the exact body and a full example.\n\n### The feed\n\n`GET /events` lists the store's events in the order the feed places them; keep the last `next_cursor` and pass it back. The cursor is a position in the feed, not an event `id`: an event is placed once it is written for good, always after everything placed before it, so a cursor never passes an event that was still about to appear. An event whose subject changes again after you read it is placed once more, with the newer state. Events are kept for 30 days unless the platform says otherwise; a cursor older than that answers **410** `cursor-expired` with `oldest_cursor`: read the current state, then continue from it.\n\n### Webhooks\n\nRegister an https endpoint on a public address (client panel \u2192 store \u2192 **API** \u2192 **Webhooks**, or `POST /webhooks`) and pick the events you want. Every delivery is signed with the endpoint's secret:\n\n```\nX-DS-Event: order.shipped\nX-DS-Delivery-Id: \nX-DS-Attempt: 1\nX-DS-Signature: t=,v1=[,v1=]\n\nexpected = HMAC_SHA256(secret, t + \".\" + raw_body)\naccept if any v1 == expected and |now \u2212 t| \u2264 300 s\n```\n\nRotate the secret with `POST /webhooks/{id}/rotate-secret` (or in the client panel): for 24 hours every delivery carries one `v1=` per secret, old and new, so switch at your pace.\n\nAnswer **2xx** quickly and do the work afterwards. Deliveries are **not ordered**: each is retried on its own, with growing delays (1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h \u2014 eight attempts unless your agreement says otherwise). A delivery that fails every attempt is given up; when the address has answered nothing with 2xx all that time, the endpoint is switched off and you are notified. Switching it back on sends what it missed \u2014 the events of the last 72 hours it listens to and never received (for a product or the delivery offer only the latest, as each carries the current state), as new deliveries a few a second, oldest first but not ordered on arrival. While the store is paused nothing is delivered but `store.paused` and `store.resumed`; the rest waits and goes out after the resume. A deleted store's deliveries stop.\n\n## Limits\n\nRequests are limited per key; a **429** carries `Retry-After`. Order quotes and placements have their own, lower limit; a checkout's live calls (rates, pickup points, the check before payment) a higher one. Failed key checks are also limited per address. The exact numbers, the number of keys and endpoints per store are part of your agreement.\n" }, "servers": [ { "url": "https://dev-v2.click2drop.eu/api" } ], "tags": [ { "name": "Store", "description": "The store behind the key." }, { "name": "Catalogue", "description": "Products, stock, prices, categories and delivery countries of the store." }, { "name": "Delivery", "description": "The delivery methods the store offers and what it charges for them." }, { "name": "Orders", "description": "Quote, place, read and cancel orders." }, { "name": "Inbox", "description": "Orders as your shop sent them, including the held ones." }, { "name": "Documents", "description": "Invoices and other documents of the orders." }, { "name": "Webhooks", "description": "Endpoints of your system that receive signed events." }, { "name": "Events", "description": "The event stream, for polling instead of webhooks." } ], "security": [ { "http": [] } ], "paths": { "/v1/me": { "get": { "operationId": "v1.me", "description": "**Scope:** any key\n\nThe store this key belongs to and what the key may do. A good first\ncall: it proves the key works and tells you the store's currency,\nmarkets and price mode.", "summary": "Who am I", "tags": [ "Store" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "store_id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "currency": { "type": "string" }, "content_language": { "type": [ "string", "null" ] }, "markets": { "type": "array", "items": { "type": "string" } }, "price_mode": { "type": "string" }, "auto_place_orders": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "key_expires_at": { "type": [ "string", "null" ] } }, "required": [ "store_id", "name", "type", "currency", "content_language", "markets", "price_mode", "auto_place_orders", "scopes", "key_expires_at" ] } }, "required": [ "data" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/products": { "get": { "operationId": "v1.products.index", "description": "**Scope:** `catalog.read`\n\nOne entry per variant, in the store's content language, with the\nstock the store may sell \u2014 the best single warehouse when the store\nships each order from one, else the sum over its markets \u2014 and the\nprices the store is set to show. Keyset-paged: pass `next_cursor` back\nto read the next page. `updated_since` (ISO 8601) narrows to the\nproducts whose content, sell price or stock changed since then, or\nwhose place in the store did (selected, paused); further back than\nevents are kept (30 days unless the platform says otherwise) it\nnarrows nothing. Our price for you (`purchase_price`) is not part of\nit \u2014 read GET /prices for those. A product\nthat leaves the catalogue is not listed any more: the event feed\nannounces it as `product.removed`. `listed=false` also returns\neligible products the store does not list right now \u2014 not selected,\nor paused by the client (they carry `listed: false`).", "summary": "List products", "tags": [ "Catalogue" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } }, { "name": "updated_since", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "listed", "in": "query", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "sku": { "type": "string" }, "name": { "type": "string" }, "about": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "features": { "type": [ "string", "null" ] }, "specifications": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "thumb_url": { "type": [ "string", "null" ] } }, "required": [ "url", "thumb_url" ] } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute": { "type": "string" }, "value": { "type": "string" } }, "required": [ "attribute", "value" ] } }, "categories": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": [ "object", "null" ], "properties": { "weight": { "type": [ "number", "null" ] }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] } }, "required": [ "weight", "width", "height", "length" ] }, "stock": { "type": "integer" }, "purchase_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "sell_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "updated_at": { "type": "string" }, "translations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "about": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "features": { "type": [ "string", "null" ] }, "specifications": { "type": [ "string", "null" ] } }, "required": [ "name", "about", "description", "features", "specifications" ] } }, "listed": { "type": "boolean" } }, "required": [ "id", "product_id", "sku", "name", "about", "description", "features", "specifications", "photos", "attributes", "categories", "dimensions", "stock", "purchase_price", "sell_price", "updated_at", "translations", "listed" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/products/{sku}": { "get": { "operationId": "v1.products.show", "description": "**Scope:** `catalog.read`\n\nOne product by SKU, in the same shape the list uses.", "summary": "Get a product", "tags": [ "Catalogue" ], "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "product_id": { "type": "integer" }, "sku": { "type": "string" }, "name": { "type": "string" }, "about": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "features": { "type": [ "string", "null" ] }, "specifications": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "thumb_url": { "type": [ "string", "null" ] } }, "required": [ "url", "thumb_url" ] } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute": { "type": "string" }, "value": { "type": "string" } }, "required": [ "attribute", "value" ] } }, "categories": { "type": "array", "items": { "type": "string" } }, "dimensions": { "type": [ "object", "null" ], "properties": { "weight": { "type": [ "number", "null" ] }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] } }, "required": [ "weight", "width", "height", "length" ] }, "stock": { "type": "integer" }, "purchase_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "sell_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "updated_at": { "type": "string" }, "translations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "about": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "features": { "type": [ "string", "null" ] }, "specifications": { "type": [ "string", "null" ] } }, "required": [ "name", "about", "description", "features", "specifications" ] } }, "listed": { "type": "boolean" } }, "required": [ "id", "product_id", "sku", "name", "about", "description", "features", "specifications", "photos", "attributes", "categories", "dimensions", "stock", "purchase_price", "sell_price", "updated_at", "translations", "listed" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/stock": { "get": { "operationId": "v1.stock.index", "description": "**Scope:** `catalog.read`\n\nThe light call for a shop that polls often: SKU and units the store\nmay sell, for every listed product \u2014 the best single warehouse when\nthe store ships each order from one, else the sum over its markets;\nthe same figure as `stock` in /products. Keyset-paged.", "summary": "List stock levels", "tags": [ "Catalogue" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": [ "string", "null" ] }, "stock": { "type": "integer" } }, "required": [ "id", "sku", "stock" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/prices": { "get": { "operationId": "v1.prices.index", "description": "**Scope:** `catalog.read`\n\nPurchase prices (what your account pays, in its currency) and \u2014 in\nautomatic price mode \u2014 the sell prices set for the store, in the\nstore's currency. `sell_price` is null in manual price mode or when\nno price was set. With \"include the fulfilment fee\" on, `sell_price` is\nthe price the buyer pays \u2014 the store's own price plus the product's\nfulfilment fee. Keyset-paged.", "summary": "List prices", "tags": [ "Catalogue" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": [ "string", "null" ] }, "purchase_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "sell_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "id", "sku", "purchase_price", "sell_price" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/categories": { "get": { "operationId": "v1.categories.index", "description": "**Scope:** `catalog.read`\n\nThe catalogue's categories as a tree, named in the store's content\nlanguage. A product's `categories` field is the path of names from the\nroot down.", "summary": "List categories", "tags": [ "Catalogue" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "children": { "type": "array", "items": {} } }, "required": [ "id", "name", "slug", "children" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/countries": { "get": { "operationId": "v1.countries.index", "description": "**Scope:** `catalog.read`\n\nThe countries THIS store delivers to: every country at least one of\nits delivery methods (GET /delivery) reaches. `recipient.country_iso2`\nof an order should be one of these; any other is refused with\n`country_not_served`.", "summary": "List delivery countries", "tags": [ "Catalogue" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "iso2": { "type": "string" }, "name": { "type": "string" } }, "required": [ "iso2", "name" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/delivery": { "get": { "operationId": "v1.delivery.index", "description": "**Scope:** `catalog.read`\n\nEvery delivery method the store offers, as set on the store's\nDelivery tab, in the store currency: per destination country the\nfree-shipping threshold and the WEIGHT BRACKETS the shop charges its\ncustomer by (kg; both ends inclusive, a weight exactly on a boundary\ntakes the LOWER bracket; `weight_to` null = no upper limit) \u2014 the\nshape of a weight-based shipping rate in Shopify or WooCommerce. A\nbracket prices one parcel: a shipment packed into several parcels pays\neach parcel's bracket, summed \u2014 except one bracket from 0 with no upper\nlimit, which is the price of the shipment however it is packed. Simple\npricing is that one bracket; advanced pricing is the platform tariff\nby weight with the client's `markup_percent` / `markup_fixed` on top,\nand follows the tariff by itself. `id` is the courier option id to\nsend in `couriers` when placing an order. `delivery_kind` is `address`\n(to the door) or `pickup_point` (a locker or parcel shop the buyer\nchooses \u2014 see GET /delivery/pickup-points; the order then needs\n`pickup_points`). A method disabled on the tab is absent, and so is a\ncountry the client unticked for it. A country with no price set yet\nis listed with empty `brackets`: the method still ships there (an\norder naming it, or naming no courier, can use it), but the shop has\nno price to show \u2014 POST /checkout/rates leaves such a method out.\nChanges arrive as the `delivery.updated` webhook.", "summary": "List delivery methods", "tags": [ "Delivery" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "carrier": { "type": "string" }, "service": { "type": "string" }, "code": { "type": "string" }, "delivery_kind": { "type": "string" }, "pricing": { "type": "string" }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "markup_percent": { "type": [ "string", "null" ] }, "markup_fixed": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "free_from": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "countries": { "type": "array", "items": { "type": "object", "properties": { "iso2": { "type": "string" }, "free_from": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "brackets": { "type": "array", "items": { "type": "object", "properties": { "weight_from": { "type": "string" }, "weight_to": { "type": [ "string", "null" ] }, "price": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } }, "required": [ "weight_from", "weight_to", "price" ] } } }, "required": [ "iso2", "free_from", "brackets" ] } } }, "required": [ "id", "carrier", "service", "code", "delivery_kind", "pricing", "price", "markup_percent", "markup_fixed", "free_from", "countries" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/delivery/pickup-points": { "get": { "operationId": "v1.delivery.pickup-points", "description": "**Scope:** `catalog.read`\n\nThe lockers and parcel shops a `pickup_point` delivery method can\ndeliver to in one country \u2014 from the platform's own directory, which\nmirrors the carrier's list nightly. `courier_option_id` is the\nmethod's `id`, `country_iso2` the recipient's country, `search`\nmatches the city, postcode, name or the carrier's id; with the buyer's\n`postal_code` and `city` the nearest points come first \u2014 by distance\nwhen we know where the postcode lies, else same postcode, then\npostcode area, then city. At most 10 results; narrow\nthe search rather than paging. Each point says what it\ntakes (`max_weight` kg, `max_dimensions` cm, longest side first; null =\nno limit) \u2014 an order whose parcel is over a point's limits is held, so\noffer only points that fit \u2014 or send the parcel and let us: `lines[]`\nas `SKU:quantity` (packed exactly as the order will be) or `weight`\nin kg, and only points that take it come back (`lines` that cannot be\npacked \u2014 a SKU the store does not list, no stock \u2014 answer 422 unless\n`weight` is sent too). `distance_km` is from\nthe buyer's postcode; `opening_hours` the week (Monday = 1) when the\ncarrier publishes it. A method the store does not offer to that\ncountry answers 422. Send the chosen point back as\n`pickup_points[][id]` (or `[external_id]`) when placing\nthe order.", "summary": "Search pickup points", "tags": [ "Delivery" ], "parameters": [ { "name": "courier_option_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "country_iso2", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 100 } }, { "name": "postal_code", "in": "query", "description": "The buyer's address: points nearest to it come first.", "schema": { "type": [ "string", "null" ], "maxLength": 20 } }, { "name": "city", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 120 } }, { "name": "weight", "in": "query", "description": "The parcel: only points that take it are listed. `lines`\n(`SKU:quantity`) packs it as the order will; `weight` (kg)\nalone filters by weight.", "schema": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000 } }, { "name": "lines[]", "in": "query", "schema": { "type": "array", "pattern": "^.+:\\d+$", "items": { "type": "string", "pattern": "^.+:\\d+$", "maxLength": 120 } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "external_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country_iso2": { "type": "string" }, "latitude": { "type": [ "string", "null" ] }, "longitude": { "type": [ "string", "null" ] }, "distance_km": { "type": [ "string", "null" ] }, "max_weight": { "type": [ "string", "null" ] }, "max_dimensions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "opening_hours": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "day": { "type": "integer" }, "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "day", "from", "to" ] } } }, "required": [ "id", "external_id", "type", "name", "address", "street", "city", "postal_code", "country_iso2", "latitude", "longitude", "distance_km", "max_weight", "max_dimensions", "opening_hours" ] } } }, "required": [ "data" ] } } } }, "422": { "description": "The courier option does not deliver to pickup points, is not offered by the store, or the country is unknown", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/checkout/rates": { "post": { "operationId": "v1.checkout.rates", "description": "**Scope:** `catalog.read`\n\nWhat a checkout offers for a cart of our products, asked live: the\ncart split into parcels by warehouse (the split the order will be\nplaced with \u2014 `packages[].id` is the shipment id an order names), and\nfor each parcel every delivery method of the store's offer that ships\nit to the buyer's country, priced by the store's offer (per parcel the\nwarehouse packs, see GET /delivery; `0.00` above the free-shipping\nthreshold; a method without a price for that country is left out),\nwith whether cash on\ndelivery is possible on it (`cod.fee` is our fee, in the store's\ncurrency). The cart-level `cod` says whether the cart may be paid on\ndelivery at all and up to how much (`max_amount`, the courier's\nceiling). `price` per line is what the buyer pays for one unit; only\nthe store's products belong in `lines`.\n\n`problems` lists lines that cannot ship, each by its own SKU\n(`not_listed`, `no_weight`, `no_stock`, `unavailable` \u2014 no price for\nthe account right now \u2014 and `country_not_served`); a cart with any of\nthem should not be checked out. The answer may lag stock by a few\nminutes; POST /orders/validate reads it live. 422 with `reason` when the cart cannot\nbe delivered at all (`country_not_served`, `currency_mismatch`). 503\nwith `reason: rates_unavailable` when prices cannot be computed on our\nside for a moment (a missing exchange rate): keep your last answer and\nask again shortly.", "summary": "Rates for a cart", "tags": [ "Delivery" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "destination": { "type": "object", "properties": { "country_iso2": { "type": "string", "minLength": 2, "maxLength": 2 }, "postal_code": { "type": [ "string", "null" ], "maxLength": 20 }, "city": { "type": [ "string", "null" ], "maxLength": 120 } }, "required": [ "country_iso2" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "maxLength": 100 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "price": { "type": [ "number", "null" ], "minimum": 0 } }, "required": [ "sku", "quantity" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "currency", "destination", "lines" ] } } } }, "responses": { "503": { "description": "Error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "packages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "sku", "quantity" ] } }, "weight": { "type": "string" }, "rates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "delivery_kind": { "type": "string" }, "price": { "type": "string" }, "eta_days": { "type": [ "integer", "null" ] }, "cod": { "type": "object", "properties": { "available": { "type": "boolean" }, "fee": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "available", "fee", "reason" ] } }, "required": [ "id", "label", "delivery_kind", "price", "eta_days", "cod" ] } } }, "required": [ "id", "lines", "weight", "rates" ] } }, "cod": { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "max_amount": { "type": [ "string", "null" ] } }, "required": [ "available", "reason", "currency", "max_amount" ] }, "problems": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "sku", "reason" ] } } }, "required": [ "currency", "packages", "cod", "problems" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders": { "get": { "operationId": "v1.orders.index", "description": "**Scope:** `orders.read`\n\nOrders placed through this store, keyset-paged, in the order they\nwere created. `state` is the same word the client panel shows:\n`awaiting_payment`, `in_preparation`, `shipped`, `partly_delivered`,\n`delivered`, `returned`, `cancelled`. `updated_since` (ISO 8601)\nnarrows to the orders that changed since then \u2014 the order itself, or\nany of its shipments, parcels, tracking events, documents or returns.\nAn order still being placed is not listed until it is placed.", "summary": "List orders", "tags": [ "Orders" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } }, { "name": "updated_since", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } }, "post": { "operationId": "v1.orders.store", "description": "**Scope:** `orders.write`\n\nPlaces the order through the store's inbox, under every rule the\nclient panel applies (verification, prices, stock over the store's\nmarkets, couriers, VAT, payment). `external_reference` \u2014 or the\n`Idempotency-Key` header \u2014 is required and unique per store: the same\nreference sent again returns the original result instead of a second\norder.\n\n**201** \u2014 placed; `order` holds it; `payment_error` says why, when\nthe payment at placement did not go through (the order then waits for\nPOST /orders/{number}/pay). **202** \u2014 waiting in the inbox, `status`\n`held` (or `received` while it is being placed): `hold_reason` says\nwhy \u2014 every reason is listed in the overview \u2014 and `hold_details`\nnames the SKUs or fields; fix the cause and POST\n/inbox/{reference}/retry (or retry it in the client panel). The\nreference is at most 120 characters and may contain `/`; amounts are\nplain decimals with at most two places. A courier option that delivers to a pickup\npoint needs the point in `pickup_points` \u2014 `{\"\": {\"id\":\n * 123}}` with our id, or `{\"external_id\": \"WAW01A\"}` with the carrier's\nown, in which case `couriers` must name the option too (the recipient's\nown address stays required; the parcel goes to the point's). A\npickup-point option is never chosen for you: an order that names no\ncourier gets the cheapest door courier. **200** \u2014 the same reference\nwas seen before.", "summary": "Place an order", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "external_reference": { "type": "string" }, "status": { "type": "string" }, "hold_reason": { "type": [ "string", "null" ] }, "hold_details": { "type": [ "object", "null" ], "additionalProperties": {} }, "payment_error": { "type": [ "string", "null" ] }, "order": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "recipient": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_iso2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "apartment_number": { "type": [ "string", "null" ] } }, "required": [ "first_name", "last_name", "email", "phone", "country_iso2", "city", "postal_code", "street", "house_number", "apartment_number" ] }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string" }, "fulfillment_fee": { "type": "string" }, "shipping": { "type": "string" }, "vat": { "type": "string" }, "cod_fee": { "type": "string" }, "grand_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "subtotal", "fulfillment_fee", "shipping", "vat", "cod_fee", "grand_total", "currency" ] }, "cod": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "comment": { "type": [ "string", "null" ] }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "pickup_point": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country_iso2": { "type": [ "string", "null" ] } }, "required": [ "external_id", "type", "name", "address", "city", "postal_code", "country_iso2" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "line_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "sku", "name", "quantity", "unit_price", "line_total", "currency" ] } }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "occurred_at", "status", "description", "location" ] } } }, "required": [ "tracking_number", "carrier", "status", "shipped_at", "delivered_at", "events" ] } } }, "required": [ "id", "status", "carrier", "service", "pickup_point", "items", "parcels" ] } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "file_name": { "type": "string" }, "download_url": { "type": "string" } }, "required": [ "id", "type", "number", "issued_at", "file_name", "download_url" ] } } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at", "can_cancel", "recipient", "totals", "cod", "comment", "shipments", "documents" ] } }, "required": [ "external_reference", "status", "hold_reason", "hold_details", "payment_error", "order" ] } }, "required": [ "data" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "external_reference": { "type": "string" }, "status": { "type": "string" }, "hold_reason": { "type": [ "string", "null" ] }, "hold_details": { "type": [ "object", "null" ], "additionalProperties": {} }, "payment_error": { "type": [ "string", "null" ] }, "order": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "recipient": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_iso2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "apartment_number": { "type": [ "string", "null" ] } }, "required": [ "first_name", "last_name", "email", "phone", "country_iso2", "city", "postal_code", "street", "house_number", "apartment_number" ] }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string" }, "fulfillment_fee": { "type": "string" }, "shipping": { "type": "string" }, "vat": { "type": "string" }, "cod_fee": { "type": "string" }, "grand_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "subtotal", "fulfillment_fee", "shipping", "vat", "cod_fee", "grand_total", "currency" ] }, "cod": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "comment": { "type": [ "string", "null" ] }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "pickup_point": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country_iso2": { "type": [ "string", "null" ] } }, "required": [ "external_id", "type", "name", "address", "city", "postal_code", "country_iso2" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "line_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "sku", "name", "quantity", "unit_price", "line_total", "currency" ] } }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "occurred_at", "status", "description", "location" ] } } }, "required": [ "tracking_number", "carrier", "status", "shipped_at", "delivered_at", "events" ] } } }, "required": [ "id", "status", "carrier", "service", "pickup_point", "items", "parcels" ] } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "file_name": { "type": "string" }, "download_url": { "type": "string" } }, "required": [ "id", "type", "number", "issued_at", "file_name", "download_url" ] } } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at", "can_cancel", "recipient", "totals", "cod", "comment", "shipments", "documents" ] } }, "required": [ "external_reference", "status", "hold_reason", "hold_details", "payment_error", "order" ] } }, "required": [ "data" ] } } } }, "202": { "description": "Accepted \u2014 waiting in the inbox", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "external_reference": { "type": "string" }, "status": { "type": "string" }, "hold_reason": { "type": [ "string", "null" ] }, "hold_details": { "type": [ "object", "null" ], "additionalProperties": {} }, "payment_error": { "type": [ "string", "null" ] }, "order": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "recipient": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_iso2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "apartment_number": { "type": [ "string", "null" ] } }, "required": [ "first_name", "last_name", "email", "phone", "country_iso2", "city", "postal_code", "street", "house_number", "apartment_number" ] }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string" }, "fulfillment_fee": { "type": "string" }, "shipping": { "type": "string" }, "vat": { "type": "string" }, "cod_fee": { "type": "string" }, "grand_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "subtotal", "fulfillment_fee", "shipping", "vat", "cod_fee", "grand_total", "currency" ] }, "cod": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "comment": { "type": [ "string", "null" ] }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "pickup_point": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country_iso2": { "type": [ "string", "null" ] } }, "required": [ "external_id", "type", "name", "address", "city", "postal_code", "country_iso2" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "line_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "sku", "name", "quantity", "unit_price", "line_total", "currency" ] } }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "occurred_at", "status", "description", "location" ] } } }, "required": [ "tracking_number", "carrier", "status", "shipped_at", "delivered_at", "events" ] } } }, "required": [ "id", "status", "carrier", "service", "pickup_point", "items", "parcels" ] } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "file_name": { "type": "string" }, "download_url": { "type": "string" } }, "required": [ "id", "type", "number", "issued_at", "file_name", "download_url" ] } } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at", "can_cancel", "recipient", "totals", "cod", "comment", "shipments", "documents" ] } }, "required": [ "external_reference", "status", "hold_reason", "hold_details", "payment_error", "order" ] } }, "required": [ "data" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{number}": { "get": { "operationId": "v1.orders.show", "description": "**Scope:** `orders.read`\n\nThe whole order: the client-facing state, the recipient, the money,\nevery shipment with its items, parcels and tracking events, and the\ndocuments with their download links.", "summary": "Get an order", "tags": [ "Orders" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "recipient": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_iso2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "apartment_number": { "type": [ "string", "null" ] } }, "required": [ "first_name", "last_name", "email", "phone", "country_iso2", "city", "postal_code", "street", "house_number", "apartment_number" ] }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string" }, "fulfillment_fee": { "type": "string" }, "shipping": { "type": "string" }, "vat": { "type": "string" }, "cod_fee": { "type": "string" }, "grand_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "subtotal", "fulfillment_fee", "shipping", "vat", "cod_fee", "grand_total", "currency" ] }, "cod": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "comment": { "type": [ "string", "null" ] }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "pickup_point": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country_iso2": { "type": [ "string", "null" ] } }, "required": [ "external_id", "type", "name", "address", "city", "postal_code", "country_iso2" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "line_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "sku", "name", "quantity", "unit_price", "line_total", "currency" ] } }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "occurred_at", "status", "description", "location" ] } } }, "required": [ "tracking_number", "carrier", "status", "shipped_at", "delivered_at", "events" ] } } }, "required": [ "id", "status", "carrier", "service", "pickup_point", "items", "parcels" ] } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "file_name": { "type": "string" }, "download_url": { "type": "string" } }, "required": [ "id", "type", "number", "issued_at", "file_name", "download_url" ] } } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at", "can_cancel", "recipient", "totals", "cod", "comment", "shipments", "documents" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{number}/tracking": { "get": { "operationId": "v1.orders.tracking", "description": "**Scope:** `orders.read`\n\nEvery parcel of the order with its tracking number, carrier, status\nand the courier's events, oldest first.", "summary": "Get tracking", "tags": [ "Orders" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "occurred_at", "status", "description", "location" ] } } }, "required": [ "tracking_number", "carrier", "status", "shipped_at", "delivered_at", "events" ] } } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{number}/returns": { "get": { "operationId": "v1.orders.returns", "description": "**Scope:** `orders.read`\n\nThe client's announcements (\"a parcel is on its way back to you\") and\nthe warehouse-side returns of the order, with their refund state.", "summary": "List returns", "tags": [ "Orders" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "announcements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "shipment_id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "courier": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "contents": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "shipment_id", "status", "courier", "tracking_number", "contents", "can_cancel", "created_at" ] } }, "returns": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": [ "string", "null" ] }, "shipment_id": { "type": [ "integer", "null" ] }, "kind": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "refund_status": { "type": [ "string", "null" ] }, "refunded_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "number", "shipment_id", "kind", "status", "refund_status", "refunded_total", "created_at" ] } } }, "required": [ "announcements", "returns" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } }, "post": { "operationId": "v1.orders.returns.announce", "description": "**Scope:** `orders.write`\n\nTells the warehouse that goods from one shipment are travelling back:\nwhich shipment (`shipment_id` from the order), the courier and the\ntracking number, optionally what is inside. Allowed once the shipment\nhas left; a shipment with a return already under way answers 409.", "summary": "Announce a return", "tags": [ "Orders" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "shipment_id": { "type": "integer" }, "courier": { "type": "string", "maxLength": 120 }, "tracking_number": { "type": "string", "maxLength": 120 }, "contents": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "shipment_id", "courier", "tracking_number" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "shipment_id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "courier": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "contents": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "shipment_id", "status", "courier", "tracking_number", "contents", "can_cancel", "created_at" ] } }, "required": [ "data" ] } } } }, "409": { "description": "Refused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/validate": { "post": { "operationId": "v1.orders.validate", "description": "**Scope:** `orders.read`\n\nThe body of POST /orders, judged by every rule the placement applies\n\u2014 the store, the recipient, the products, the couriers and points per\nshipment, cash on delivery, stock as it is now \u2014 and nothing written:\nno inbox row, no order, no event. **200** `{ok: true}`: the order\nwould be placed. **422** problem+json carrying `{ok: false, reason,\ndetails}`: `reason` is\nthe `hold_reason` it would be held with (`no_stock`,\n`country_not_served`, `recipient_invalid`, `pickup_point_invalid`,\n`cod_unavailable`, `no_door_courier`, `unmapped_sku`, `not_selected`,\n`verification_required`, `store_paused`, `payment_failed` (a card the\naccount does not hold), `courier_unavailable` (a courier named for a\nparcel that does not go from its warehouse), `split_changed` \u2014 the cart\nno longer splits into the parcels `couriers` names \u2014 or\n`invalid_request` for a body that is not an order, with\n`details.errors`). Stock and the card are judged again when the order\narrives. A store that approves orders by hand still answers 200: the\norder will arrive and wait for that approval.", "summary": "Check an order before the buyer pays", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_reference": { "type": [ "string", "null" ], "maxLength": 120 }, "external_number": { "type": [ "string", "null" ], "maxLength": 120 }, "recipient": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "country_iso2": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 100 }, "postal_code": { "type": "string", "maxLength": 20 }, "street": { "type": "string", "maxLength": 200 }, "house_number": { "type": [ "string", "null" ], "description": "A shop's \"address line 2\" arrives here (\"Klatka B, pi\u0119tro 3,\n m. 12\"): 20 characters refused real buyers at the check before\npayment, while the placement takes any length (2026-10-16).", "maxLength": 100 }, "apartment_number": { "type": [ "string", "null" ], "maxLength": 100 } }, "required": [ "first_name", "last_name", "country_iso2", "city", "postal_code", "street" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "variant_id": { "type": [ "integer", "null" ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "recipient_price": { "type": [ "number", "null" ], "description": "What the recipient pays per unit of this line, gross, in\n`currency` \u2014 the invoice to the recipient prints every line\nwhen every line has one. Give it on every line or on none.", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" } }, "required": [ "quantity" ] }, "minItems": 1, "maxItems": 200 }, "comment": { "type": [ "string", "null" ], "maxLength": 500 }, "payment_route": { "anyOf": [ { "$ref": "#/components/schemas/PaymentRoute" }, { "type": "null" } ] }, "payment_method_id": { "type": [ "string", "null" ], "maxLength": 100 }, "cod_amount": { "type": [ "number", "null" ], "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" }, "total": { "type": [ "number", "null" ], "description": "The recipient's price: what the buyer paid (or owes) the shop for\nthe whole order, in the shop's currency. The invoice to the\nrecipient is made of it, when the store issues invoices (a store\nsetting, off unless the client switches it on; the invoice is the\nclient's paper to their buyer, not an official tax document); an\norder without it is placed without an invoice.", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "shipment_totals": { "type": [ "array", "null" ], "description": "An order that ships in several shipments gets an invoice in\nEACH, so one `total` cannot serve: give the recipient's total\nper shipment (quote shipment id => amount), or `recipient_price`\non every line plus `shipment_shipping`. With one total only, such\nan order is placed without invoices and you hear why.", "items": { "type": "number", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" } }, "shipment_shipping": { "type": [ "array", "null" ], "description": "Quote shipment id => the shipping charged to the recipient in\nthat shipment's invoice (with `recipient_price` on every line).", "items": { "type": "number", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" } }, "couriers": { "type": [ "array", "null" ], "description": "Quote shipment id => courier option id, both from POST /orders/quote.", "items": { "type": "integer" } }, "pickup_points": { "type": [ "array", "null" ], "description": "Quote shipment id => the pickup point for a courier option that\ndelivers to one: our `id` (GET /delivery/pickup-points) or the\ncarrier's own `external_id`.", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ], "maxLength": 100 } } } } }, "required": [ "recipient", "lines" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "422": { "description": "Would not be placed", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "ok": { "type": "boolean" }, "reason": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "ok", "reason", "details", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/quote": { "post": { "operationId": "v1.orders.quote", "description": "**Scope:** `orders.write`\n\nPrices a would-be order \u2014 items, fulfilment fee, shipping per\nshipment, VAT, total \u2014 without creating anything. Same body as\nplacing one; `external_reference` is not needed. The order may split\ninto several shipments when its products sit in different warehouses;\neach shipment shows the courier that would be used and the\nalternatives. An option whose `delivery_kind` is `pickup_point`\ndelivers to a locker or parcel shop: to place with it, send the\npoint for that shipment in `pickup_points` (see GET\n/delivery/pickup-points). Priced by the very check the placement\nruns: the same couriers, every shipment with one, a pickup point that\ntakes its parcel, and with `cod_amount` cash on delivery under its\ncaps \u2014 its fee (`cod_fee`) in the totals. A problem the shop must fix\nanswers 422 with the `reason` the placement would hold it with.", "summary": "Quote an order", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currency": { "type": "string" }, "subtotal": { "type": "string" }, "fulfillment_fee": { "type": "string" }, "shipping": { "type": "string" }, "vat": { "type": "string" }, "grand_total": { "type": "string" }, "cod_fee": { "type": "string" }, "cod": { "type": [ "object", "null" ], "properties": { "available": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "fee": { "type": "string" } }, "required": [ "available", "reason", "fee" ] }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "line_total": { "type": "string" } }, "required": [ "sku", "quantity", "unit_price", "line_total" ] } }, "vat_rate": { "type": "string" }, "shipping": { "type": "string" }, "total": { "type": "string" }, "courier": { "type": [ "object", "null" ], "properties": { "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] } }, "required": [ "carrier", "service" ] }, "courier_options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "carrier": { "type": "string" }, "service": { "type": "string" }, "cost": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "eta_days": { "type": [ "integer", "null" ] }, "delivery_kind": { "type": "string" } }, "required": [ "id", "carrier", "service", "cost", "currency", "eta_days", "delivery_kind" ] } } }, "required": [ "id", "items", "vat_rate", "shipping", "total", "courier", "courier_options" ] } } }, "required": [ "currency", "subtotal", "fulfillment_fee", "shipping", "vat", "grand_total", "cod_fee", "cod", "shipments" ] } }, "required": [ "data" ] } } } }, "422": { "description": "The request is invalid or the order cannot be built", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "reason", "details", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{number}/cancel": { "post": { "operationId": "v1.orders.cancel", "description": "**Scope:** `orders.write`\n\nAllowed while the order is unpaid and nothing has left the warehouse\n\u2014 the same rule as the Cancel button in the client panel. Afterwards\ncancelling is a support request, and this answers 409\n`order-not-cancellable`; while a payment of the same order is running\nit answers 409 `order-busy` (check the order, then retry). Cancelling an\norder that is already cancelled answers 200 with the order, so a\nrepeated call (an answer lost on the way) is safe. The inbox entry\nkeeps `placed` \u2014 it tells that an order was made; the order's own\n`state` says `cancelled`.", "summary": "Cancel an order", "tags": [ "Orders" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "Why the shop cancelled; shown on the order's history.", "maxLength": 300 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "recipient": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_iso2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "apartment_number": { "type": [ "string", "null" ] } }, "required": [ "first_name", "last_name", "email", "phone", "country_iso2", "city", "postal_code", "street", "house_number", "apartment_number" ] }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string" }, "fulfillment_fee": { "type": "string" }, "shipping": { "type": "string" }, "vat": { "type": "string" }, "cod_fee": { "type": "string" }, "grand_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "subtotal", "fulfillment_fee", "shipping", "vat", "cod_fee", "grand_total", "currency" ] }, "cod": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "comment": { "type": [ "string", "null" ] }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "service": { "type": [ "string", "null" ] }, "pickup_point": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "postal_code": { "type": "string" }, "country_iso2": { "type": [ "string", "null" ] } }, "required": [ "external_id", "type", "name", "address", "city", "postal_code", "country_iso2" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "line_total": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "sku", "name", "quantity", "unit_price", "line_total", "currency" ] } }, "parcels": { "type": "array", "items": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ] }, "carrier": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "occurred_at": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] } }, "required": [ "occurred_at", "status", "description", "location" ] } } }, "required": [ "tracking_number", "carrier", "status", "shipped_at", "delivered_at", "events" ] } } }, "required": [ "id", "status", "carrier", "service", "pickup_point", "items", "parcels" ] } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "file_name": { "type": "string" }, "download_url": { "type": "string" } }, "required": [ "id", "type", "number", "issued_at", "file_name", "download_url" ] } } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at", "can_cancel", "recipient", "totals", "cod", "comment", "shipments", "documents" ] } }, "required": [ "data" ] } } } }, "409": { "description": "Refused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{number}/pay": { "post": { "operationId": "v1.orders.pay", "description": "**Scope:** `orders.write`\n\nTakes the money for an order that is waiting for payment \u2014 the same\nroutes as the client panel: the waterfall (balance, then credit, then\ncard), or one of them. An order already paid answers 200 with the\norder, so a repeated call is safe. `payment_method_id` must be one of\nthe account's saved cards. A card that needs 3-D Secure answers 202 with\nthe address to send the customer to. A refused payment answers 409\n`payment-failed`; a payment while another payment or a cancellation of\nthe same order is running answers 409 `order-busy` (check the order,\nthen retry).", "summary": "Pay an order", "tags": [ "Orders" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_route": { "anyOf": [ { "$ref": "#/components/schemas/PaymentRoute" }, { "type": "null" } ] }, "payment_method_id": { "type": [ "string", "null" ], "maxLength": 100 } } } } } }, "responses": { "200": { "description": "Paid", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at" ] }, "requires_action": { "type": "boolean" }, "authentication_url": { "type": [ "string", "null" ] } }, "required": [ "order", "requires_action", "authentication_url" ] } }, "required": [ "data" ] } } } }, "409": { "description": "Refused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "202": { "description": "Needs 3-D Secure \u2014 send the customer to authentication_url", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "number": { "type": "string" }, "external_reference": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "placed_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "number", "external_reference", "state", "placed_at", "paid_at", "grand_total", "tracking_numbers", "updated_at" ] }, "requires_action": { "type": "boolean" }, "authentication_url": { "type": [ "string", "null" ] } }, "required": [ "order", "requires_action", "authentication_url" ] } }, "required": [ "data" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{number}/returns/{announcement}": { "delete": { "operationId": "v1.orders.returns.cancel", "description": "**Scope:** `orders.write`\n\nPossible while the warehouse has not matched the parcel yet.", "summary": "Cancel a return announcement", "tags": [ "Orders" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "announcement", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "shipment_id": { "type": "integer" }, "status": { "type": [ "string", "null" ] }, "courier": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "contents": { "type": [ "string", "null" ] }, "can_cancel": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "shipment_id", "status", "courier", "tracking_number", "contents", "can_cancel", "created_at" ] } }, "required": [ "data" ] } } } }, "409": { "description": "Refused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/inbox": { "get": { "operationId": "v1.inbox.index", "description": "**Scope:** `orders.read`\n\nEvery order received from this store, keyset-paged; `status` narrows\nto one state: `received` (arrived, being placed), `placed` (an order\nwas made \u2014 its own `state` is in /orders), `held` (stopped, see\n`hold_reason`), `rejected` (dropped, never placed), `cancelled` (the\nshop cancelled a placed order), `superseded` (replaced by a corrected\ncopy under the same reference \u2014 history).", "summary": "List inbox entries", "tags": [ "Inbox" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "received", "placed", "held", "rejected", "cancelled", "superseded", null ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "external_reference": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "hold_reason": { "type": [ "string", "null" ] }, "hold_details": { "type": [ "object", "null" ], "additionalProperties": {} }, "order_number": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ] }, "placed_at": { "type": [ "string", "null" ] } }, "required": [ "external_reference", "external_number", "status", "hold_reason", "hold_details", "order_number", "received_at", "placed_at" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/inbox/{reference}": { "get": { "operationId": "v1.inbox.show", "description": "**Scope:** `orders.read`", "summary": "Get an inbox entry", "tags": [ "Inbox" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "external_reference": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "hold_reason": { "type": [ "string", "null" ] }, "hold_details": { "type": [ "object", "null" ], "additionalProperties": {} }, "order_number": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ] }, "placed_at": { "type": [ "string", "null" ] } }, "required": [ "external_reference", "external_number", "status", "hold_reason", "hold_details", "order_number", "received_at", "placed_at" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/inbox/{reference}/retry": { "post": { "operationId": "v1.inbox.retry", "description": "**Scope:** `orders.write`\n\nRuns the intake again for an order that stopped \u2014 after the cause was\nfixed (the product listed, stock back, the address completed) \u2014 or\napproves one waiting for approval. Answers the entry as it is now.\nAn entry no longer waiting (placed, rejected, cancelled) answers\n`409 inbox-not-open`; one being placed this very moment answers\n`409 inbox-busy` \u2014 retry in a moment.", "summary": "Retry a held entry", "tags": [ "Inbox" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "external_reference": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "hold_reason": { "type": [ "string", "null" ] }, "hold_details": { "type": [ "object", "null" ], "additionalProperties": {} }, "order_number": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ] }, "placed_at": { "type": [ "string", "null" ] } }, "required": [ "external_reference", "external_number", "status", "hold_reason", "hold_details", "order_number", "received_at", "placed_at" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "409": { "description": "Not waiting, or busy right now", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" }, "inbox_status": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id", "inbox_status" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/inbox/{reference}/reject": { "post": { "operationId": "v1.inbox.reject", "description": "**Scope:** `orders.write`\n\nDrops an order that should not be placed. It stays in the inbox as\nrejected; the same reference can never be placed again. The same\n`409`s as a retry: not waiting any more, or busy right now.", "summary": "Reject a held entry", "tags": [ "Inbox" ], "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 300 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "external_reference": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "hold_reason": { "type": [ "string", "null" ] }, "hold_details": { "type": [ "object", "null" ], "additionalProperties": {} }, "order_number": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ] }, "placed_at": { "type": [ "string", "null" ] } }, "required": [ "external_reference", "external_number", "status", "hold_reason", "hold_details", "order_number", "received_at", "placed_at" ] } }, "required": [ "data" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "409": { "description": "Not waiting, or busy right now", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" }, "inbox_status": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id", "inbox_status" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/orders/{number}/documents": { "get": { "operationId": "v1.orders.documents", "description": "**Scope:** `orders.read`\n\nInvoices and other documents of the order, current versions only,\neach with a download link that works with the same key.", "summary": "List an order's documents", "tags": [ "Documents" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "file_name": { "type": "string" }, "download_url": { "type": "string" } }, "required": [ "id", "type", "number", "issued_at", "file_name", "download_url" ] } } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/documents/{document}/download": { "get": { "operationId": "v1.documents.download", "description": "**Scope:** `orders.read`\n\nThe file itself (usually a PDF), as an attachment. Only a current\nversion: a document replaced by a newer one (an invoice reissued) or\nwithdrawn answers 404 \u2014 read the order's documents again for the\ncurrent one.", "summary": "Download a document", "tags": [ "Documents" ], "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/webhooks": { "get": { "operationId": "v1.webhooks.index", "description": "**Scope:** `webhooks.manage`\n\nEvery endpoint of the store. The signing secret is never returned\nhere \u2014 only once, when the endpoint is created.", "summary": "List endpoints", "tags": [ "Webhooks" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "disabled_at": { "type": [ "string", "null" ] }, "last_delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "previous_secret_expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "events", "is_active", "consecutive_failures", "disabled_at", "last_delivered_at", "created_at", "previous_secret_expires_at" ] } } }, "required": [ "data" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } }, "post": { "operationId": "v1.webhooks.store", "description": "**Scope:** `webhooks.manage`\n\nRegisters an https URL of your system. `events` is the list of event\ntypes to receive; empty means every event. A key subscribes only to\nwhat it may read: `order.*` needs `orders.read`; `product.*`,\n`price.updated`, `stock.updated` and `delivery.updated` need\n`catalog.read` (`store.paused` and `store.resumed` need neither). A\nkey without both read scopes must list its events; anything else is\n`403 insufficient-scope`. Each event type may go to\na limited number of endpoints of the store (one, unless the platform\nsays otherwise) \u2014 an endpoint that takes every event takes every type,\nand a type already taken is refused with `409 limit-reached`. The URL\nmust be public (no private or loopback addresses). The signing secret\nis returned **once**, in this response \u2014 store it.", "summary": "Create an endpoint", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "disabled_at": { "type": [ "string", "null" ] }, "last_delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "previous_secret_expires_at": { "type": [ "string", "null" ] }, "secret": { "type": "string" } }, "required": [ "id", "name", "url", "events", "is_active", "consecutive_failures", "disabled_at", "last_delivered_at", "created_at", "previous_secret_expires_at", "secret" ] } }, "required": [ "data" ] } } } }, "409": { "description": "Refused: private URL, or an event type already taken by another endpoint", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/webhooks/{endpoint}": { "get": { "operationId": "v1.webhooks.show", "description": "**Scope:** `webhooks.manage`", "summary": "Get an endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "disabled_at": { "type": [ "string", "null" ] }, "last_delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "previous_secret_expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "events", "is_active", "consecutive_failures", "disabled_at", "last_delivered_at", "created_at", "previous_secret_expires_at" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } }, "patch": { "operationId": "v1.webhooks.update", "description": "**Scope:** `webhooks.manage`\n\nChange the URL, the name, the events or switch it on and off. The\nsame per-event limit and the same read scopes as on creation apply\nto the endpoint as it will be \u2014 a key cannot redirect an endpoint\nthat hears events it may not read. Switching an endpoint back on\nresets its failure count and sends it again what it missed: every\nevent of the last 72 hours it listens to and has not received, oldest\nfirst.", "summary": "Update an endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "disabled_at": { "type": [ "string", "null" ] }, "last_delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "previous_secret_expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "url", "events", "is_active", "consecutive_failures", "disabled_at", "last_delivered_at", "created_at", "previous_secret_expires_at" ] } }, "required": [ "data" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "409": { "description": "Refused: private URL, or an event type already taken by another endpoint", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } }, "delete": { "operationId": "v1.webhooks.destroy", "description": "**Scope:** `webhooks.manage`\n\nRemoves the endpoint and its delivery log.", "summary": "Delete an endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "string" } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/webhooks/{endpoint}/rotate-secret": { "post": { "operationId": "v1.webhooks.rotate-secret", "description": "**Scope:** `webhooks.manage`\n\nA new secret, returned **once** in this response. For 24 hours every\ndelivery is signed with both \u2014 `X-DS-Signature` carries one `v1=` per\nsecret \u2014 so your system can switch to the new one without missing a\ndelivery; afterwards only the new one signs.", "summary": "Rotate the signing secret", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "consecutive_failures": { "type": "integer" }, "disabled_at": { "type": [ "string", "null" ] }, "last_delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "previous_secret_expires_at": { "type": [ "string", "null" ] }, "secret": { "type": "string" } }, "required": [ "id", "name", "url", "events", "is_active", "consecutive_failures", "disabled_at", "last_delivered_at", "created_at", "previous_secret_expires_at", "secret" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/webhooks/{endpoint}/test": { "post": { "operationId": "v1.webhooks.test", "description": "**Scope:** `webhooks.manage`\n\nDelivers a `ping` to the endpoint right away, signed like every other\nevent, and returns the delivery with your system's answer.", "summary": "Send a test event", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "delivery_id": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "response_code": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "delivery_id", "event", "status", "attempts", "response_code", "error", "next_attempt_at", "delivered_at", "created_at" ] } }, "required": [ "data" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/webhooks/{endpoint}/deliveries": { "get": { "operationId": "v1.webhooks.deliveries", "description": "**Scope:** `webhooks.manage`\n\nThe delivery log of the endpoint, newest first, keyset-paged (pass\n`next_cursor` back for older ones): every event sent, how many\nattempts it took, what your system answered.", "summary": "List deliveries", "tags": [ "Webhooks" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "delivery_id": { "type": "string" }, "event": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "response_code": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "delivery_id", "event", "status", "attempts", "response_code", "error", "next_attempt_at", "delivered_at", "created_at" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "404": { "description": "Not found in this store", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "403": { "description": "The key lacks the scope; the account is not verified or not active; or the platform does not take this account's orders yet", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "410": { "description": "The store behind the key was deleted", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } }, "/v1/events": { "get": { "operationId": "v1.events.index", "description": "**Scope:** `orders.read` or `catalog.read` (each hears the events it may read)\n\nThe store's event stream, for a system that would rather poll than\nreceive webhooks \u2014 the same envelopes the webhooks carry. Keep the\nlast `next_cursor` you saw and pass it back to read only what is new:\nthe last page still carries it (null only before the store has any\nevent), and `has_more` says whether to ask again right away. The\ncursor is a position in the feed, not an event `id`: an event written\nlater always comes later, so the cursor never passes one; an event\nwhose subject changed again after you read it comes once more.\n\nA key hears what it may read: `order.*` with `orders.read`, the\ncatalogue and `delivery.updated` with `catalog.read`, `store.paused`\nand `store.resumed` with either; a key with neither scope is `403`.\nAn event says WHAT changed; its `data` is the thing as it is when you\nread it, not a snapshot of the moment \u2014 read twice, the same event\nmay show a later state. Without a cursor the feed starts at the\noldest event kept. Events are kept for a limited time\n(30 days unless the platform says otherwise); a cursor older than the\nevents still kept answers `410 cursor-expired` with `oldest_cursor`:\nread the current state, then continue from it.", "summary": "List events", "tags": [ "Events" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "created_at": { "type": "string" }, "store_id": { "type": "integer" }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "created_at", "store_id", "data" ] } }, "next_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" } }, "required": [ "data", "next_cursor", "has_more" ] } } } }, "410": { "description": "The cursor is older than the events still kept", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" }, "oldest_cursor": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id", "oldest_cursor" ] } } } }, "403": { "description": "The key reads neither orders nor the catalogue", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string" } }, "required": [ "type", "title", "status", "detail", "request_id" ] } } } }, "422": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The problem type; switch on its last segment, the slug \u2014 see /docs/api/errors" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "errors": { "type": "object", "description": "Field name \u2192 its messages", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "request_id": { "type": "string", "description": "Quote it to support; also in the X-Request-Id header" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "401": { "description": "The key is missing, unknown, revoked or expired", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "423": { "description": "The store is paused", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "429": { "description": "Too many requests \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } }, "503": { "description": "The platform is under maintenance \u2014 wait the seconds in Retry-After", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A stable error slug to switch on" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": [ "string", "null" ] }, "request_id": { "type": "string", "description": "Quote it to support" } }, "required": [ "type", "title", "status", "request_id" ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "A store API key from the client panel: `Authorization: Bearer ds_live_\u2026`", "scheme": "bearer" } }, "schemas": { "CreateOrderRequest": { "type": "object", "description": "The body of POST /orders, /orders/quote and /orders/validate.\n\nEvery amount is a plain decimal with at most two places \u2014 `19.99` or\n`\"19.99\"`, never `1e3`, ` 10` or `19.999` (decided 2026-10-15: a looser\n\"numeric\" let such values through to the money arithmetic, which refused\nthem with a 500).", "properties": { "external_reference": { "type": [ "string", "null" ], "maxLength": 120 }, "external_number": { "type": [ "string", "null" ], "maxLength": 120 }, "recipient": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 100 }, "last_name": { "type": "string", "maxLength": 100 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 }, "phone": { "type": [ "string", "null" ], "maxLength": 40 }, "country_iso2": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 100 }, "postal_code": { "type": "string", "maxLength": 20 }, "street": { "type": "string", "maxLength": 200 }, "house_number": { "type": [ "string", "null" ], "description": "A shop's \"address line 2\" arrives here (\"Klatka B, pi\u0119tro 3,\n m. 12\"): 20 characters refused real buyers at the check before\npayment, while the placement takes any length (2026-10-16).", "maxLength": 100 }, "apartment_number": { "type": [ "string", "null" ], "maxLength": 100 } }, "required": [ "first_name", "last_name", "country_iso2", "city", "postal_code", "street" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "variant_id": { "type": [ "integer", "null" ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 }, "recipient_price": { "type": [ "number", "null" ], "description": "What the recipient pays per unit of this line, gross, in\n`currency` \u2014 the invoice to the recipient prints every line\nwhen every line has one. Give it on every line or on none.", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" } }, "required": [ "quantity" ] }, "minItems": 1, "maxItems": 200 }, "comment": { "type": [ "string", "null" ], "maxLength": 500 }, "payment_route": { "anyOf": [ { "$ref": "#/components/schemas/PaymentRoute" }, { "type": "null" } ] }, "payment_method_id": { "type": [ "string", "null" ], "maxLength": 100 }, "cod_amount": { "type": [ "number", "null" ], "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" }, "total": { "type": [ "number", "null" ], "description": "The recipient's price: what the buyer paid (or owes) the shop for\nthe whole order, in the shop's currency. The invoice to the\nrecipient is made of it, when the store issues invoices (a store\nsetting, off unless the client switches it on; the invoice is the\nclient's paper to their buyer, not an official tax document); an\norder without it is placed without an invoice.", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "shipment_totals": { "type": [ "array", "null" ], "description": "An order that ships in several shipments gets an invoice in\nEACH, so one `total` cannot serve: give the recipient's total\nper shipment (quote shipment id => amount), or `recipient_price`\non every line plus `shipment_shipping`. With one total only, such\nan order is placed without invoices and you hear why.", "items": { "type": "number", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" } }, "shipment_shipping": { "type": [ "array", "null" ], "description": "Quote shipment id => the shipping charged to the recipient in\nthat shipment's invoice (with `recipient_price` on every line).", "items": { "type": "number", "pattern": "^\\d{1,10}(\\.\\d{1,2})?$" } }, "couriers": { "type": [ "array", "null" ], "description": "Quote shipment id => courier option id, both from POST /orders/quote.", "items": { "type": "integer" } }, "pickup_points": { "type": [ "array", "null" ], "description": "Quote shipment id => the pickup point for a courier option that\ndelivers to one: our `id` (GET /delivery/pickup-points) or the\ncarrier's own `external_id`.", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "external_id": { "type": [ "string", "null" ], "maxLength": 100 } } } } }, "required": [ "recipient", "lines" ], "title": "CreateOrderRequest" }, "PaymentRoute": { "type": "string", "description": "Where the money for a payment is taken from. {@see self::Waterfall} is the default everywhere: drain the client's own balance, then the credit line, then charge the remainder to the card. The other three exist because a client placing their own order may want to decide \u2014 \"put this one on the card, keep the credit * line for the big order on Friday\" \u2014 and a screen that only states what will happen is not a choice. A single-source route does NOT fall back: picking \"Balance\" and not having enough is a refusal, not a silent card charge. That is the whole point of picking it. Cash on delivery is deliberately NOT a route: a COD order is paid by the client through one of these four like any other, and the amount the courier collects at the door is the CLIENT's retail money travelling to them through us ({@see CodCollectionService}).\n", "enum": [ "waterfall", "card", "balance", "credit" ], "title": "PaymentRoute" }, "WebhookEndpointRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 60 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "events": { "type": [ "array", "null" ], "items": { "type": "string", "description": "`ping` is the test button's, never a subscription: dropped\nsilently it left an empty list \u2014 every event.", "enum": [ "order.placed", "order.held", "order.rejected", "order.paid", "order.shipped", "order.tracking_updated", "order.delivered", "order.cancelled", "order.document_added", "order.return_announced", "order.return_updated", "order.refunded", "product.updated", "product.removed", "price.updated", "stock.updated", "delivery.updated", "store.paused", "store.resumed" ] } }, "is_active": { "type": "boolean", "description": "Absent = unchanged (on creation: on). A null is not \"off\"." } }, "required": [ "url" ], "title": "WebhookEndpointRequest" } }, "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" ] } } } } } }, "webhooks": { "order.placed": { "post": { "summary": "An order was placed", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.placed`. Not something you call.\n\nThe shop's order became a platform order: it is reserved at the warehouse and, when `paid` is true, already paid. Fires once per order, after `POST /orders` (or a retry from the inbox) succeeded \u2014 and before any other event of that order (its payment, its documents).\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.placed" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "paid": { "type": "boolean", "description": "Whether the payment went through at placement" }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.placed", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "paid": true, "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "in_preparation", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.held": { "post": { "summary": "An order stopped in the inbox", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.held`. Not something you call.\n\nThe order could not be placed yet. `data` is the inbox entry as `GET /inbox/{reference}` shows it now; `reason` is why it stopped at the moment of this event. Fix the cause and `POST /inbox/{reference}/retry`, or reject it.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.held" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "external_reference": { "type": "string", "description": "The reference your shop sent" }, "external_number": { "type": [ "string", "null" ], "description": "The shop's own order number" }, "status": { "type": "string", "description": "received \u00b7 placed \u00b7 held \u00b7 rejected \u00b7 cancelled \u00b7 superseded" }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it waits now: unmapped_sku \u00b7 not_selected \u00b7 no_stock \u00b7 country_not_served \u00b7 cod_unavailable \u00b7 recipient_invalid \u00b7 pickup_point_invalid \u00b7 no_door_courier \u00b7 payment_failed \u00b7 payment_lapsed \u00b7 verification_required \u00b7 manual_review \u00b7 store_paused \u00b7 split_changed \u00b7 courier_unavailable \u00b7 no_courier \u00b7 other" }, "hold_details": { "type": [ "object", "null" ], "description": "The SKUs or fields at fault", "additionalProperties": true }, "order_number": { "type": [ "string", "null" ], "description": "The order it became, once placed" }, "received_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "reason": { "type": "string", "description": "Why it stopped at this event: unmapped_sku \u00b7 not_selected \u00b7 no_stock \u00b7 country_not_served \u00b7 cod_unavailable \u00b7 recipient_invalid \u00b7 pickup_point_invalid \u00b7 no_door_courier \u00b7 payment_failed \u00b7 payment_lapsed \u00b7 verification_required \u00b7 manual_review \u00b7 store_paused \u00b7 split_changed \u00b7 courier_unavailable \u00b7 no_courier \u00b7 other" } } } } }, "example": { "id": 4812, "type": "order.held", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "external_reference": "order-10433", "external_number": "#10433", "status": "held", "hold_reason": "unmapped_sku", "hold_details": { "skus": [ "SKU-NOPE" ] }, "order_number": null, "received_at": "2026-09-10T11:59:58+00:00", "placed_at": null, "reason": "unmapped_sku" } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.rejected": { "post": { "summary": "A held order was rejected", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.rejected`. Not something you call.\n\nThe client rejected an order that stopped in the inbox, in the client panel: it will never be placed. Rejecting with `POST /inbox/{reference}/reject` sends no event \u2014 the answer to that call says it. `data` is the inbox entry as `GET /inbox/{reference}` shows it.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.rejected" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "external_reference": { "type": "string", "description": "The reference your shop sent" }, "external_number": { "type": [ "string", "null" ], "description": "The shop's own order number" }, "status": { "type": "string", "description": "received \u00b7 placed \u00b7 held \u00b7 rejected \u00b7 cancelled \u00b7 superseded" }, "hold_reason": { "type": [ "string", "null" ], "description": "Why it waits now: unmapped_sku \u00b7 not_selected \u00b7 no_stock \u00b7 country_not_served \u00b7 cod_unavailable \u00b7 recipient_invalid \u00b7 pickup_point_invalid \u00b7 no_door_courier \u00b7 payment_failed \u00b7 payment_lapsed \u00b7 verification_required \u00b7 manual_review \u00b7 store_paused \u00b7 split_changed \u00b7 courier_unavailable \u00b7 no_courier \u00b7 other" }, "hold_details": { "type": [ "object", "null" ], "description": "The SKUs or fields at fault", "additionalProperties": true }, "order_number": { "type": [ "string", "null" ], "description": "The order it became, once placed" }, "received_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "reason": { "type": [ "string", "null" ], "description": "The rejection's reason, when one was given" } } } } }, "example": { "id": 4812, "type": "order.rejected", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "external_reference": "WEB-10231", "external_number": "#10433", "status": "rejected", "hold_reason": "no_stock", "hold_details": null, "order_number": null, "received_at": "2026-09-10T11:59:58+00:00", "placed_at": null, "reason": "Out of stock" } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.paid": { "post": { "summary": "An order was paid", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.paid`. Not something you call.\n\nThe money arrived \u2014 through the balance, the credit line, a card or a later `POST /orders/{number}/pay`. `order.paid_at` carries the moment.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.paid" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.paid", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "in_preparation", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.shipped": { "post": { "summary": "A parcel left the warehouse", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.shipped`. Not something you call.\n\nOne parcel of the order got a tracking number. An order that splits across warehouses fires this once per parcel; `order.tracking_numbers` lists every one so far.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.shipped" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ], "description": "The courier's tracking number" }, "carrier": { "type": [ "string", "null" ], "description": "The courier" }, "status": { "type": [ "string", "null" ], "description": "Parcel status: registered \u00b7 ordered \u00b7 picked_up \u00b7 in_transit \u00b7 out_for_delivery \u00b7 delivered \u00b7 exception \u00b7 returned \u00b7 unknown" }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.shipped", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "tracking_number": "00340434161094015902", "carrier": "DHL", "status": "in_transit", "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "shipped", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [ "00340434161094015902" ], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.tracking_updated": { "post": { "summary": "A parcel moved", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.tracking_updated`. Not something you call.\n\nThe courier reported a new scan for one parcel. The full history is on `GET /orders/{number}/tracking`.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.tracking_updated" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ], "description": "Which parcel" }, "status": { "type": [ "string", "null" ], "description": "The parcel status after this scan" }, "description": { "type": [ "string", "null" ], "description": "The courier's own words" }, "occurred_at": { "type": [ "string", "null" ], "description": "When the scan happened, ISO 8601" }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.tracking_updated", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "tracking_number": "00340434161094015902", "status": "out_for_delivery", "description": "Out for delivery", "occurred_at": "2026-09-12T07:40:00+00:00", "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "shipped", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [ "00340434161094015902" ], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.delivered": { "post": { "summary": "A parcel was delivered", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.delivered`. Not something you call.\n\nOne parcel reached the recipient. When every parcel has, `order.state` becomes `delivered`.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.delivered" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "tracking_number": { "type": [ "string", "null" ], "description": "Which parcel" }, "carrier": { "type": [ "string", "null" ], "description": "The courier" }, "status": { "type": [ "string", "null" ], "description": "Always `delivered`" }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.delivered", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "tracking_number": "00340434161094015902", "carrier": "DHL", "status": "delivered", "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "delivered", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [ "00340434161094015902" ], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.cancelled": { "post": { "summary": "An order was cancelled", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.cancelled`. Not something you call.\n\nBy your system (`POST /orders/{number}/cancel`), by the client in the panel, or by the platform when an unpaid order passed its payment deadline. `reason` is the sentence recorded on the order.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.cancelled" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "Why" }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.cancelled", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "reason": "Cancelled by the client.", "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "cancelled", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.document_added": { "post": { "summary": "A document was added", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.document_added`. Not something you call.\n\nAn invoice or another document became available. Download it with `GET /documents/{id}/download` using the same key.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.document_added" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "document_id": { "type": "integer", "description": "Pass it to the download endpoint" }, "type": { "type": [ "string", "null" ], "description": "invoice \u00b7 proforma_invoice \u00b7 corrective_invoice \u00b7 \u2026" }, "number": { "type": [ "string", "null" ], "description": "The document number" }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.document_added", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "document_id": 915, "type": "invoice", "number": "FV/2026/09/0412", "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "in_preparation", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.return_announced": { "post": { "summary": "A return was announced", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.return_announced`. Not something you call.\n\nSomebody told the warehouse a parcel is travelling back \u2014 your system through `POST /orders/{number}/returns`, or the client in the panel. Fires again when the announcement is matched to received goods or cancelled (`announcement.status`).\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.return_announced" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "announcement": { "type": "object", "properties": { "id": { "type": "integer", "description": "Announcement id" }, "shipment_id": { "type": "integer", "description": "Which shipment of the order" }, "status": { "type": "string", "description": "announced \u00b7 matched \u00b7 cancelled" }, "courier": { "type": [ "string", "null" ], "description": "Courier the goods travel back with" }, "tracking_number": { "type": [ "string", "null" ], "description": "Its tracking number" }, "contents": { "type": [ "string", "null" ], "description": "What is inside, free text" }, "can_cancel": { "type": "boolean", "description": "Whether DELETE /orders/{number}/returns/{id} would still work" }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.return_announced", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "announcement": { "id": 31, "shipment_id": 512, "status": "announced", "courier": "InPost", "tracking_number": "620000012345", "contents": "1 \u00d7 SKU-546, unopened", "can_cancel": true, "created_at": "2026-09-14T09:12:00+00:00" }, "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "delivered", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.return_updated": { "post": { "summary": "A return changed", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.return_updated`. Not something you call.\n\nA warehouse-side return was opened or moved: received, refunded, closed. `return.refund_status` and `return.refunded_total` follow the money.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.return_updated" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "return": { "type": "object", "properties": { "number": { "type": [ "string", "null" ], "description": "Return number" }, "shipment_id": { "type": [ "integer", "null" ], "description": "Which shipment of the order" }, "kind": { "type": [ "string", "null" ], "description": "cancelled \u00b7 undelivered \u00b7 customer_return \u00b7 early_refund" }, "status": { "type": [ "string", "null" ], "description": "requested \u00b7 approved \u00b7 awaiting_receipt \u00b7 needs_review \u00b7 received \u00b7 partially_received \u00b7 closed \u00b7 rejected \u00b7 cancelled" }, "refund_status": { "type": [ "string", "null" ], "description": "pending \u00b7 partially_refunded \u00b7 refunded" }, "refunded_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "created_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.return_updated", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "return": { "number": "RT-2026-000018", "shipment_id": 512, "kind": "customer_return", "status": "received", "refund_status": "refunded", "refunded_total": { "amount": "25.000000", "currency": "EUR" }, "created_at": "2026-09-16T10:00:00+00:00" }, "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "returned", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "order.refunded": { "post": { "summary": "An order was refunded", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `order.refunded`. Not something you call.\n\nMoney went back to the client's balance for this order, in part or in full. `payment_status` is `partially_refunded` or `refunded`.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "order.refunded" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "payment_status": { "type": "string", "description": "partially_refunded \u00b7 refunded" }, "order": { "type": "object", "description": "The order as GET /orders returns it", "properties": { "number": { "type": "string", "description": "Order number" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference your shop sent" }, "state": { "type": "string", "description": "awaiting_payment \u00b7 in_preparation \u00b7 shipped \u00b7 partly_delivered \u00b7 delivered \u00b7 returned \u00b7 cancelled" }, "placed_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "paid_at": { "type": [ "string", "null" ], "description": "ISO 8601" }, "grand_total": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "tracking_numbers": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": [ "string", "null" ], "description": "ISO 8601" } } } } } } }, "example": { "id": 4812, "type": "order.refunded", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "payment_status": "partially_refunded", "order": { "number": "PL100926-7K2Q", "external_reference": "order-10432", "state": "returned", "placed_at": "2026-09-10T12:00:00+00:00", "paid_at": "2026-09-10T12:00:01+00:00", "grand_total": { "amount": "61.500000", "currency": "EUR" }, "tracking_numbers": [], "updated_at": "2026-09-10T12:00:01+00:00" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "product.updated": { "post": { "summary": "A product changed or was listed", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `product.updated`. Not something you call.\n\nThe product as `GET /products/{sku}` returns it now: content, photos, attributes, stock and prices. Fires when the product was added to the store, when its content changed, and on a full sync.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "product.updated" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Variant id" }, "product_id": { "type": "integer", "description": "Parent product id" }, "sku": { "type": "string", "description": "SKU" }, "name": { "type": "string", "description": "In the store's content language" }, "about": { "type": [ "string", "null" ], "description": "Short text, HTML" }, "description": { "type": [ "string", "null" ], "description": "Long text, HTML" }, "features": { "type": [ "string", "null" ], "description": "One per line" }, "specifications": { "type": [ "string", "null" ], "description": "HTML" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Full size" }, "thumb_url": { "type": [ "string", "null" ], "description": "Catalogue size" } } } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "e.g. Colour" }, "value": { "type": "string", "description": "e.g. Black" } } } }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category path, root first" }, "dimensions": { "type": [ "object", "null" ], "properties": { "weight": { "type": [ "number", "null" ] }, "width": { "type": [ "number", "null" ] }, "height": { "type": [ "number", "null" ] }, "length": { "type": [ "number", "null" ] } } }, "stock": { "type": "integer", "description": "Units over the store's markets" }, "purchase_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "sell_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "updated_at": { "type": "string", "description": "ISO 8601" } } } } }, "example": { "id": 4812, "type": "product.updated", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "id": 19, "product_id": 1415, "sku": "546", "name": "Portable Cooler and Heater, ADM 2-in-1", "about": "

The ADM 2-in-1 combines cooling, heating and humidification in one compact unit.

", "description": "

\u2026

", "features": "Remote and touch controls\nAdjustable airflow", "specifications": "

\u2026

", "photos": [ { "url": "https://example.com/storage/546/photo.jpg", "thumb_url": "https://example.com/storage/546/conversions/thumb.jpg" } ], "attributes": [ { "attribute": "Colour", "value": "White" } ], "categories": [ "Home", "Climate" ], "dimensions": { "weight": 3.2, "width": 22, "height": 31.5, "length": 18 }, "stock": 85, "purchase_price": { "amount": "10.000000", "currency": "EUR" }, "sell_price": { "amount": "19.99", "currency": "EUR" }, "updated_at": "2026-09-10T11:58:00+00:00" } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "product.removed": { "post": { "summary": "A product left the store", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `product.removed`. Not something you call.\n\nThe product is no longer listed \u2014 removed by the client, or no longer available in their catalogue. Hide or unpublish it in your shop.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "product.removed" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Variant id" }, "sku": { "type": [ "string", "null" ], "description": "SKU" } } } } }, "example": { "id": 4812, "type": "product.removed", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "id": 19, "sku": "546" } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "price.updated": { "post": { "summary": "A price changed", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `price.updated`. Not something you call.\n\nThe purchase price and, in automatic price mode, the sell price of one product. `sell_price` is null in manual mode or when none was set.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "price.updated" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Variant id" }, "sku": { "type": [ "string", "null" ], "description": "SKU" }, "purchase_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "sell_price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } } } } } }, "example": { "id": 4812, "type": "price.updated", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "id": 19, "sku": "546", "purchase_price": { "amount": "10.000000", "currency": "EUR" }, "sell_price": { "amount": "19.99", "currency": "EUR" } } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "stock.updated": { "post": { "summary": "Stock changed", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `stock.updated`. Not something you call.\n\nUnits available over the store's markets for one product. Repeated changes while a delivery is pending are folded into one.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Catalogue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "stock.updated" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "Variant id" }, "sku": { "type": [ "string", "null" ], "description": "SKU" }, "stock": { "type": "integer", "description": "Units available" } } } } }, "example": { "id": 4812, "type": "stock.updated", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "id": 19, "sku": "546", "stock": 85 } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "delivery.updated": { "post": { "summary": "The delivery offer changed", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `delivery.updated`. Not something you call.\n\nThe client changed which delivery methods the store offers or what it charges for them \u2014 the whole offer as `GET /delivery` returns it now. Rebuild your shop's shipping options from `methods`; `id` is the courier option id for `couriers` when placing an order.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Delivery" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "delivery.updated" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Carrier service id \u2014 the courier option id in `couriers`" }, "carrier": { "type": "string", "description": "Carrier name" }, "service": { "type": "string", "description": "Service name" }, "code": { "type": "string", "description": "`division.service` codes, unique across carriers" }, "pricing": { "type": "string", "description": "`simple` (one price for every country) or `advanced` (the platform tariff by weight and country, plus the client's markup)" }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } }, "description": "Simple pricing: the one price for every country; null in advanced pricing" }, "markup_percent": { "type": [ "string", "null" ], "description": "Advanced pricing: the percentage added to the platform tariff; null otherwise" }, "markup_fixed": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } }, "description": "Advanced pricing: the fixed amount added per parcel; null otherwise" }, "free_from": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } }, "description": "Order subtotal from which delivery is free; null when never" }, "countries": { "type": "array", "description": "The destinations this method is offered to. `brackets` are weight-based rates (kg), the shape of a Shopify / WooCommerce shipping rate; simple pricing is one bracket from 0 with no upper limit", "items": { "type": "object", "properties": { "iso2": { "type": "string", "description": "Destination country" }, "free_from": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } }, "brackets": { "type": "array", "items": { "type": "object", "properties": { "weight_from": { "type": "string", "description": "Chargeable weight from, kg (inclusive)" }, "weight_to": { "type": [ "string", "null" ], "description": "Chargeable weight to, kg (exclusive); null = no upper limit" }, "price": { "type": "object", "properties": { "amount": { "type": "string", "description": "A decimal string: a sell price to the cent, a purchase price with up to six places" }, "currency": { "type": "string", "description": "ISO 4217" } } } } } } } } } } } } } } } }, "example": { "id": 4812, "type": "delivery.updated", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "methods": [ { "id": 3, "carrier": "DHL", "service": "Standard", "code": "dhl-pl.standard", "pricing": "advanced", "price": null, "markup_percent": "25.000", "markup_fixed": { "amount": "0.500000", "currency": "EUR" }, "free_from": { "amount": "60.000000", "currency": "EUR" }, "countries": [ { "iso2": "DE", "free_from": { "amount": "60.000000", "currency": "EUR" }, "brackets": [ { "weight_from": "0.000", "weight_to": "2.000", "price": { "amount": "4.990000", "currency": "EUR" } }, { "weight_from": "2.000", "weight_to": null, "price": { "amount": "7.990000", "currency": "EUR" } } ] }, { "iso2": "PL", "free_from": null, "brackets": [ { "weight_from": "0.000", "weight_to": null, "price": { "amount": "3.490000", "currency": "EUR" } } ] } ] } ] } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "store.paused": { "post": { "summary": "The store was paused", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `store.paused`. Not something you call.\n\nNothing goes out or comes in until it is resumed; the API answers 423 meanwhile. Paused by the client, or by the platform with a reason.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Store" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "store.paused" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": {} } } }, "example": { "id": 4812, "type": "store.paused", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": {} } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "store.resumed": { "post": { "summary": "The store was resumed", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `store.resumed`. Not something you call.\n\nBack in service; a full sync follows.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Store" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "store.resumed" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": {} } } }, "example": { "id": 4812, "type": "store.resumed", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": {} } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } }, "ping": { "post": { "summary": "Test delivery", "description": "**Webhook** \u2014 we `POST` this to your endpoint; the `X-DS-Event` header is `ping`. Not something you call.\n\nSent by the \"Send test\" button or `POST /webhooks/{id}/test`. Signed like every other delivery, so use it to verify your signature check.\n\nHeaders: `X-DS-Event` (the type), `X-DS-Delivery-Id` (unique per delivery, the same on every retry), `X-DS-Attempt`, `X-DS-Signature` (`t=,v1=`, with a second `,v1=` for 24 hours after the secret is rotated \u2014 one per secret; accept when any `v1` equals `HMAC_SHA256(secret, t + \".\" + raw body)` and `t` is at most 300 seconds from now). Answer 2xx within 10 seconds and do the work afterwards.", "tags": [ "Store" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "created_at", "store_id", "data" ], "properties": { "id": { "type": "integer", "description": "Event id. The same event may come again with a newer state: treat it as an update, not a duplicate" }, "type": { "type": "string", "const": "ping" }, "created_at": { "type": "string", "description": "When it happened, ISO 8601" }, "store_id": { "type": "integer", "description": "The store" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Always `pong`" } } } } }, "example": { "id": 4812, "type": "ping", "created_at": "2026-09-10T12:00:00+00:00", "store_id": 7, "data": { "message": "pong" } } } } }, "responses": { "2XX": { "description": "Acknowledged. Anything else is retried with growing delays." } } } } } }