SKUU Connect API

SKUU Connect links a commerce platform to the SKUU inventory network. The
integration coordinates products, inventory, orders, fulfilment and returns
through a small set of customer endpoints and signed events.

Start in TESTING. Production stays disabled until both teams sign off.

How to use these docs

The documentation has two layers:

Guides explain what each capability does, who owns each action and how
the operational flow fits together.
API Reference defines the exact endpoints, fields, examples,
authentication and responses your implementation must support.

Read the Guides first. Use the linked API Reference while building.

Before you build

Agree the following with SKUU:

the base URL of your customer-hosted TESTING API;
the SKUU-provided TESTING webhook URL where your platform sends signed events;
a customer-issued bearer token and shared HMAC secret for TESTING;
the physical location IDs included in your catalogue; and
the virtual SKUU_Network location ID assigned by SKUU.

SKUU_Network represents network availability. It is not a physical warehouse.
Keep TESTING and production credentials separate.

Capabilities

Guide	What it explains
Products	How SKUU reads a complete catalogue, product images and stock baseline
Inventory	How physical and network stock stay in sync
Orders	How paid consumer orders become seller orders
Fulfilment	How shipment tracking returns to the consumer order
Returns	How return requests are received and native seller returns are created

Responsibility split

Party	Responsibility
Your platform	Own its products, physical stock, native orders and native returns
SKUU	Match products, route network orders and coordinate network availability
Both teams	Protect credentials, preserve stable identifiers and prove the integration in TESTING

Security model

Requests from SKUU to your API use the customer-issued bearer token. Requests
with a body are also signed with the shared HMAC secret. Events from your
platform to SKUU are signed with the same environment-specific HMAC secret.

The receiver verifies the signature before processing the body. The API
Reference shows the exact requirements on each operation: Read
products uses
the bearer token, Set virtual SKUU_Network
inventory
uses bearer plus HMAC, and Deliver a signed Connect
event uses HMAC.

Stable identities

Use stable opaque identifiers in the exact fields defined by each operation.
The API Reference states which party creates each identifier and where it is
echoed or reused. Event IDs and external references make retries safe; never
infer business meaning from an identifier's format.

Testing and go-live

Implementation happens in TESTING. Each capability is checked for correct
routing, safe retries, stable identities and absence of duplicate side effects.
Both teams then complete one joint end-to-end journey.

Recurring traffic and production open only after written sign-off from both
teams.