Inventory

The store's platform stays the source of truth for the store's physical stock. SKUU is the only one that writes the SKUU_Network location. Every quantity is an absolute level. Replaying the same value does not add or subtract stock. For incoming events, timestamp checks prevent an older state from replacing a newer one.

1. The online store sends `inventory.updated`

The online store. A shirt sells in the store; stock at location 1 goes from 3 to 2.
The store's platform. Sends one inventory.updated event to SKUU with the variant, the location, the new absolute quantity 2, and changed_at, the moment the stock changed.
SKUU. Checks the signature, then looks up the newest changed_at it already holds for this variant at this location. If the event is newer, SKUU applies it. If it is older, SKUU ignores it with 200. If its timestamp is identical but the quantity differs, SKUU returns 409 timestamp_conflict. That is how a late event can never roll the truth back.
SKUU. Recalculates what the other shops can sell of this article and writes the result to their SKUU_Network locations (direction 2, at their side).
SKUU. Answers 200. Invalid events receive a permanent 4xx with an error code; see Errors and retries.

Example: the inventory.updated event

{
  "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"
  }
}

All fields in `data`

Field in `data`	Required	What it means
`variant_id`	Required	Finds the variant sent in the catalogue. A variant SKUU has not imported yet receives `404 unknown_variant`. After a complete catalogue read, send the current quantity with a new event ID.
`location_id`	Required	One of the physical locations on the environment sheet, as a whole number written as a string. An unconfigured location receives `422 unknown_location`.
`available_quantity`	Required	The new absolute quantity at that location.
`changed_at`	Optional, strongly recommended	Decides which event is newer. Give every stock state a strictly later `changed_at`, down to the millisecond where needed; two events with the same `changed_at` and different quantities keep the first one. Without it SKUU falls back to `occurred_at` from the envelope.

One event covers one variant at one location. A sale of three different articles is three events. An exact replay of an earlier event is received and changes nothing.

2. SKUU calls `PUT /inventory`

Another shop. A shop in the network has 3 of a shirt this store does not have.
SKUU. Calls the store's PUT /inventory with that variant, the store's SKUU_Network location id, and the absolute quantity 3.
The store's platform. Sets 3 on the SKUU_Network location and answers 200 with the three fields it received, same values and types. Extra response fields are ignored. Any other answer counts as a failure, and SKUU retries on every sync cycle until it succeeds.
The online store. Now shows the shirt as available. When a customer buys it, the order goes to SKUU as a seller order; see Orders.
The store's platform, optionally. If the store's system emits its own inventory.updated for the SKUU_Network location after SKUU's write, send it; SKUU recognises the echo and does nothing.

Example: the PUT /inventory request

{"variant_id": "V-123-38-BLK", "location_id": "900", "available_quantity": 3}

All fields in the request

Field	Required	What it means
`variant_id`	Required	The variant SKUU is updating, by the store's `variant_id`.
`location_id`	Required	Always the store's `SKUU_Network` location id. SKUU never writes to a physical location.
`available_quantity`	Required	The new absolute network quantity. Replace the previous value; the same value again changes nothing.

Apply each incoming PUT /inventory before returning its receipt. The payload has no timestamp or version, so it cannot identify a late request as stale. Do not acknowledge writes and then apply them asynchronously out of order; the recurring sync reconciles failed writes.

The next page is Orders. The exact contract is on Send an event and Set network inventory.

1. The online store sends inventory.updated

2. SKUU calls PUT /inventory

1. The online store sends `inventory.updated`

2. SKUU calls `PUT /inventory`