Checklist

Hand this page to whoever builds the integration, whether that is a person or an AI assistant. Every rule here is explained in a guide and written out exactly in the API Reference.

Endpoints the store hosts

The six endpoints

Endpoint	Used for	Guide
`GET /products?limit=100&cursor=…`	SKUU reads the catalogue in pages	Products
`PUT /inventory`	SKUU sets the `SKUU_Network` quantity of one variant	Inventory
`POST /orders`	SKUU creates a paid shipping order for the store to ship	Orders
`PUT /orders/{order_id}/tracking`	SKUU adds tracking to the seller order	Fulfilment
`POST /cancel`	SKUU stops a shipping order before it ships	Cancellation
`POST /returns`	SKUU registers a return on the store's own order so the store can refund the customer	Returns

Every request carries the store's bearer token. Requests with a body carry X-SKUU-Signature. Return 200 with the required receipt fields. A success message is optional; extra response fields are ignored.

Events the store sends

One URL, one envelope, five event values: inventory.updated, order.created, order.cancelled, fulfillment.shipped, return.created. Signed with the shared secret. Full examples are on Send an event.

Which id goes where

Field	Comes from
`order.created` → `line_item_id`	The store's own line id
`order.created` → `fulfillment_location_id`	`"900"` (the store's `SKUU_Network` id) for lines the network ships
`order.created` → `skuu_external_ref`	SKUU's order `external_ref`, only when the store's platform echoes an order SKUU created
`order.cancelled` → `order_id`	The seller order id from `order.created`; the shipping order id from `POST /orders` when the store cannot ship
`POST /orders` → `external_ref`	SKUU. Store it next to the `order_id` returned.
`POST /orders` → `line_items[].external_ref`	SKUU. Store it per line.
`fulfillment.shipped` → `order_id`	The `order_id` returned from `POST /orders`
`fulfillment.shipped` → `external_ref`	SKUU's order `external_ref`
`fulfillment.shipped` → `line_items[].external_ref`	SKUU's line `external_ref`
`PUT /orders/{order_id}/tracking` → path `order_id`	The seller order id from `order.created`
`PUT …/tracking` → `line_items[].line_item_id`	The store's `line_item_id` from `order.created`
`return.created` → `order_id`	The shipping order id from `POST /orders`
`return.created` → `lines[].external_ref`	SKUU's line `external_ref` from that shipping order
`return.created` → `lines[].order_line_id`	The store's own line id
`POST /returns` → `order_id`	The store's order id from `order.created`
`POST /returns` → `lines[].order_line_id`	The store's `line_item_id` from `order.created`
`POST /cancel` → `order_id`	The shipping order ID from `POST /orders`

Rules

Location ids are whole numbers as strings, "900" not "WH-9". UUIDs cannot be used.
Every product has a brand and at least one public HTTPS image. Every variant has a size; use exactly One size for an article without one.
Every variant lists every agreed physical location and SKUU_Network, zeros included. SKUU_Network starts at 0; only SKUU writes to it.
Stock quantities are absolute. Give every stock change a strictly later changed_at.
A variant is unknown to SKUU until it appears in a completed catalogue pull. Stock events for it receive 404 unknown_variant until then.
Send order.created only when paid, in the store's currency, with the full delivery address: name, street, city, postcode, country. Send explicit 0 for shipping_cost and total_discounts when they are zero.
An order is final once received. To cancel it before shipment, send order.cancelled for the whole order; after shipment the customer waits for delivery and then returns the goods.
Never send order.created for an order SKUU created. If the store's platform does it anyway, keep the skuu_ship tag in data.tags or send skuu_external_ref; without either the order is recorded as the store's own sale.
Retry only on no answer or 5xx, with the same bytes and the same event_id, at least three times over fifteen minutes. Permanent errors receive 4xx; correct the cause before sending a new event. A 200 ends delivery retries and may acknowledge a valid no-op.

Before writing to SKUU

The store's signing produces sha256=4d87a87b…acc4 for the test vector.
GET /products returns the whole catalogue with stable cursors and a null cursor only on the last page.
The store's shop_slug, SKUU_Network id and test webhook URL are on the environment sheet.

Build with AI

Copy this prompt into a coding assistant. The documentation has an MCP server at https://docs.skuu.io/mcp; if the assistant cannot use MCP, it can read the Markdown pages directly.

Build a SKUU Connect integration in this project.
Read https://docs.skuu.io/llms.txt, then the Checklist, Connecting, Authentication, Errors and retries, Products and Inventory guides, plus their OpenAPI definitions. Read each later capability before implementing it.
Inspect this project's existing products, variants, locations, orders and return flow. Reuse those objects. Ask me for missing non-secret settings; stage named environment variables for credentials. Never ask me to paste secrets in chat.
Start with GET /products and PUT /inventory, then a signed inventory.updated event. Validate the published signing vector. Use my environment's location IDs and wait for a complete catalogue import before sending stock events.
Implement the remaining four hosted endpoints and four event types in the guide order, preserving the SKUU order and line references. Use the error codes to distinguish permanent rejections from retries. Prove replays cannot create duplicate orders, stock changes, cancellations, tracking notifications or returns.
Report what works locally and which joint SKUU checks remain.

The next page is Connecting.