REST API / Inventory

Inventory

The stock ledger behind your catalogue. Every change to a variant's stock is recorded with the quantity before and after, so you can reconcile your own numbers against ours rather than guessing why a level moved.

Note

This endpoint needs the inventory:read access right, which is separate from products:read. A key that syncs your catalogue does not read its history unless you switch this on under Settings → API Keys → Access rights.

GET/v1/inventory/movements

List stock movements

Every stock change on variants in your catalogue, newest first, 100 per page. Each row carries `quantity_before` and `quantity_after` alongside the signed `change`, so a movement is auditable on its own without replaying the whole history. Movements caused by an order also carry `order_id` and `order_number`. Pair `since` with the timestamp of your last successful sync to poll incrementally.

Query parameters

product_iduuid

optional

Only movements for variants of this product

variant_iduuid

optional

Only movements for this one variant

sincestring

optional

ISO 8601 date/time. Only movements recorded at or after this timestamp.

pageinteger

optional

Page number (1-based). Fixed at 100 rows per page.Default: 1

Response

200 OK

{
  "data": [
    {
      "id": "sm-001",
      "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "variant_id": "var-001",
      "sku": "OCT-WHT-M",
      "quantity_before": 144,
      "quantity_after": 142,
      "change": -2,
      "reason": "order_placed",
      "order_id": "ord-001",
      "order_number": 42,
      "created_at": "2025-06-24T09:00:00.000Z"
    },
    {
      "id": "sm-002",
      "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "variant_id": "var-001",
      "sku": "OCT-WHT-M",
      "quantity_before": 100,
      "quantity_after": 144,
      "change": 44,
      "reason": "supplier_edit",
      "order_id": null,
      "order_number": null,
      "created_at": "2025-06-22T14:10:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 100,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Movement reasons

Every movement carries one of six reasons. The first four are recorded by the code path that caused them; the last two are the catch-alls.

order_placedStock reserved when a reseller placed an order. Always carries order_id and order_number.

order_cancelledA whole order was cancelled and its stock returned.

item_cancelledIndividual items were cancelled from an order that otherwise stands — see the order's cancellations.

return_restockedA return was received and the goods put back into sellable stock.

supplier_editThe supplier changed the number themselves. Also the fallback for any change that arrived without a reason attached.

bulk_importA catalogue import wrote the level. Inferred from the writer rather than tagged, so treat it as “a machine did this”, not as proof of an import.