Connecting

There is no connect call, because a connection is a configuration that both sides hold. Once the five values below are in place, SKUU can call the store's API and the store's platform can send events to SKUU.

Step 0: the onboarding call

On the onboarding call we agree everything the connection needs: the store's API root for testing, the bearer token issued to SKUU, the shared HMAC secret, the store's physical location ids, and the SKUU_Network location id that SKUU assigns. The call ends with the store's shop_slug, the test webhook URL and an environment sheet that lists all of it. If the store's API restricts callers by IP address, SKUU's outbound addresses are shared on the same call.

No onboarding call planned yet?

Pick a slot and we set up the store's test environment together.

SKUU calls the store's API

The store hosts an API root per environment. SKUU appends fixed paths to it and sends the store's bearer token on every request. Requests with a body are also signed.

GET  {your_api_root}/products
PUT  {your_api_root}/inventory
POST {your_api_root}/orders
PUT  {your_api_root}/orders/{order_id}/tracking
POST {your_api_root}/returns
POST {your_api_root}/cancel

Authorization: Bearer <token issued to SKUU>
X-SKUU-Signature: sha256=<HMAC of the raw body>     (only on requests with a body)

The prefix is yours, for example https://api.example.com/skuu/v1. The final path segments are fixed. Build /products and /inventory first; the other four come with Orders, Fulfilment, Cancellation and Returns.

The store's platform calls SKUU

Every event is one signed JSON request to one SKUU URL. No bearer token in this direction, only the signature. All five events use the same envelope; only event and data change.

Testing:     POST https://sync.skuu.net/webhooks/connect/{shop_slug}
Production:  POST https://prod.skuu.net/webhooks/connect/{shop_slug}
Content-Type: application/json
X-SKUU-Signature: sha256=<HMAC of the raw body>

{
  "spec_version": "1",
  "event": "inventory.updated",
  "event_id": "evt_01JABC123",
  "occurred_at": "2026-07-17T12:00:00Z",
  "data": {
    "variant_id": "V-123-38-BLK",
    "location_id": "1",
    "available_quantity": 2,
    "changed_at": "2026-07-17T11:59:58Z"
  }
}

If SKUU does not answer, or answers 5xx, send the same bytes again with the same event_id: at least three attempts spread over at least fifteen minutes.

The five values

Who creates each value

Value	Who creates it
The store's API root, one per environment	The store
A bearer token for SKUU	The store
A shared HMAC secret, one per environment	Either side, agreed once
The store's physical location ids, as whole numbers	The store
The `SKUU_Network` location id	SKUU

Keep testing and production credentials separate. Exchange secrets over the channel agreed with SKUU, never in tickets or chat.

Environment sheet

SKUU fills this sheet in together with the store, and it is the source of truth for that environment, including which capabilities are switched on. These are example values:

Example environment sheet

Field	Testing	Production
The store's API root	`https://api.example.com/skuu/v1`	`https://api.example.com/skuu/v1`
SKUU webhook URL	`https://sync.skuu.net/webhooks/connect/example`	`https://prod.skuu.net/webhooks/connect/example`
Physical location ids	`1`, `2`	`1`, `2`
`SKUU_Network` location id	`900`	`900`
Switched on	Products, Inventory, Orders, Fulfilment, Returns	Products, Inventory, Orders, Fulfilment, Returns

How to know it works

SKUU reads the catalogue. GET /products calls arrive with the store's token. The first milestone is a complete run with no validation errors.
The store sends one inventory.updated event for a real variant. 401 means the signature or the URL is wrong. 200 means SKUU received it.
A 4xx response gives a permanent error: correct the cause before sending a new event. A 200 ends delivery retries; exact duplicates, older stock states and recognised echoes are valid no-ops. See Errors and retries.

https://sync.skuu.net/health tells whether SKUU is up. It says nothing about the store's connection.

The next page is Authentication.