Inventory

Retrieve the inventory overview

Requires scope merchant-inventory-read.

Retrieves the store’s inventory overview: product counts by stock state (tracked, in stock, out of stock, low, negative).

Authorization

merchantKey

X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

`application/json`

curl -X GET "https://example.com/inventory" \  -H "X-Client-Key: {{merchantKey}}"

{  "success": true,  "data": {    "total_products": 9,    "tracked_products": 8,    "untracked_products": 1,    "in_stock": 8,    "out_of_stock": 1,    "low_stock": 2,    "negative_stock": 0  }}

List inventory levels

Requires scope merchant-inventory-read.

Lists on-hand product and variant stock levels, ordered by product p_id. Filters product by p_id or slug and barcode by exact product barcode; when both are supplied they are ANDed. Unresolved product references return 404. Includes inactive variants and published or unpublished products; omits soft-deleted products. Each product lists all of its variants (no per-product cap); use a small limit for products with many variants. No per-location levels.

Authorization

merchantKey

X-Client-Key<token>

In: header

Query Parameters

limit?|

Range1 <= value <= 100

starting_after?string|null

product?string

Lengthlength <= 255

barcode?string

Lengthlength <= 100

Header Parameters

X-Client-Key*string

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

`application/json`

curl -X GET "https://example.com/inventory/levels?limit=2&starting_after=eyJwX2lkIjoyMDQxNywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" \  -H "X-Client-Key: {{merchantKey}}"

{  "data": [    {      "p_id": 20418,      "slug": "homemade-chapman",      "barcode": null,      "stock": 60,      "effective_tracking": true,      "variants": [        {          "p_id": 7731,          "sku": "ADF-CHP-50CL",          "title": "50cl",          "stock": 36,          "is_active": true,          "effective_tracking": true        },        {          "p_id": 7732,          "sku": "ADF-CHP-1L",          "title": "1 litre",          "stock": 24,          "is_active": true,          "effective_tracking": true        }      ]    }  ],  "has_more": true,  "next_cursor": "eyJwX2lkIjoyMDQxOCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}

Adjust an inventory level

Requires scope merchant-inventory-update.

Sets a tracked product or variant on-hand quantity with expected_stock compare-and-set, or applies a tracked delta, and writes an adjustment audit row with a configured reason code. Body product/variant references outside this store return 404. A stale expected_stock returns 409 with current_stock; refresh the level before retrying. Idempotency-Key is optional. One item per call; no per-location stock, bulk adjustments, purchase orders or forecasts, or check against open-order reservations.

Authorization

merchantKey

X-Client-Key<token>

In: header

Header Parameters

X-Client-Key*string

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

product*string

Lengthlength <= 255

variant?|

Range1 <= value

mode*string

Value in

"set"
"delta"

quantity*integer

Range-1000000 <= value <= 1000000

expected_stock?integer

Range-1000000 <= value <= 1000000

reason_code*string

Value in

"correction"
"count"
"damage"
"received"
"return"
"theft"
"other"

note?|

Lengthlength <= 500

Response Body

`application/json`

curl -X POST "https://example.com/inventory/levels/adjustments" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "product": "20417",    "mode": "set",    "quantity": 44,    "expected_stock": 42,    "reason_code": "count"  }'

{  "status": "success",  "message": "Inventory level adjusted.",  "data": {    "result": "adjusted",    "level": {      "product_p_id": 20417,      "variant_p_id": null,      "mode": "set",      "before": 42,      "change": 2,      "after": 44,      "reason_code": "count"    },    "adjustment": {      "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b13",      "type": "adjustment",      "quantity_before": 42,      "quantity_change": 2,      "quantity_after": 44,      "reason": "Physical count",      "reason_code": "count",      "scope": "product",      "product": {        "id": 20417,        "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "slug": "jollof-rice-party-pack"      },      "variant": null,      "order": null,      "shortfall": {        "captured": false,        "quantity": 0      },      "created_at": "2026-10-04T12:00:00+01:00"    }  }}

Retrieve product stock history

Requires scope merchant-inventory-detail.

Retrieves the stock-movement history for one product.

Authorization

merchantKey

X-Client-Key<token>

In: header

Path Parameters

product*string

Query Parameters

limit?|

Range1 <= value <= 100

starting_after?string|null

type?string|null

Header Parameters

X-Client-Key*string

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

`application/json`

curl -X GET "https://example.com/inventory/products/20417/history?limit=2" \  -H "X-Client-Key: {{merchantKey}}"

{  "data": [    {      "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b11",      "type": "sale",      "quantity_before": 44,      "quantity_change": -2,      "quantity_after": 42,      "reason": "Order 26-0924-58213",      "reason_code": null,      "scope": "product",      "product": {        "id": 20417,        "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "slug": "jollof-rice-party-pack"      },      "variant": null,      "order": {        "id": 58213,        "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01"      },      "shortfall": {        "captured": false,        "quantity": 0      },      "created_at": "2026-09-24T13:42:00+01:00"    },    {      "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b10",      "type": "restock",      "quantity_before": 24,      "quantity_change": 20,      "quantity_after": 44,      "reason": "Morning batch",      "reason_code": null,      "scope": "product",      "product": {        "id": 20417,        "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "slug": "jollof-rice-party-pack"      },      "variant": null,      "order": null,      "shortfall": {        "captured": false,        "quantity": 0      },      "created_at": "2026-09-24T07:05:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6IjAxOWEzYTBlLTZkMjEtN2I1NC04ZTkwLTJmNGE2YzhlMGIxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}

List stock adjustments

Requires scope merchant-stock_adjustments-read.

Lists stock adjustments: the store’s stock audit trail.

Authorization

merchantKey

X-Client-Key<token>

In: header

Query Parameters

limit?|

Range1 <= value <= 100

starting_after?string|null

type?string|null

product_id?|

Formatuuid

date_from?|

Formatdate-time

date_to?|

Formatdate-time

Header Parameters

X-Client-Key*string

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

`application/json`

curl -X GET "https://example.com/inventory/adjustments?limit=2&date_from=2026-09-24T00%3A00%3A00%2B01%3A00&date_to=2026-09-24T23%3A59%3A59%2B01%3A00" \  -H "X-Client-Key: {{merchantKey}}"

{  "data": [    {      "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b12",      "type": "restock",      "quantity_before": 12,      "quantity_change": 24,      "quantity_after": 36,      "reason": "Afternoon batch",      "reason_code": null,      "scope": "variant",      "product": {        "id": 20418,        "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22",        "title": "Homemade Chapman",        "slug": "homemade-chapman"      },      "variant": {        "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31",        "title": "50cl",        "option_values": {          "Size": "50cl"        }      },      "order": null,      "shortfall": {        "captured": false,        "quantity": 0      },      "created_at": "2026-09-24T15:30:00+01:00"    },    {      "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b11",      "type": "sale",      "quantity_before": 44,      "quantity_change": -2,      "quantity_after": 42,      "reason": "Order 26-0924-58213",      "reason_code": null,      "scope": "product",      "product": {        "id": 20417,        "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21",        "title": "Jollof Rice Party Pack",        "slug": "jollof-rice-party-pack"      },      "variant": null,      "order": {        "id": 58213,        "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01"      },      "shortfall": {        "captured": false,        "quantity": 0      },      "created_at": "2026-09-24T13:42:00+01:00"    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6IjAxOWEzYTBlLTZkMjEtN2I1NC04ZTkwLTJmNGE2YzhlMGIxMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}

Create a stock adjustment

Requires scope merchant-inventory-update.

Applies a stock delta to products and writes the audit-trail entry. A single adjustment answers the stock-movement object (the history and audit rows list the same one); a bulk restock names each skipped product by id (p_id) and uid.

Authorization

merchantKey

X-Client-Key<token>

In: header

Header Parameters

X-Client-Key*string

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

product_ids*array<string>

Items1 <= items

variant_id?|

Formatuuid

quantity_change*integer

type*string

Value in

"restock"
"adjustment"
"damage"

reason*string

Lengthlength <= 500

Response Body

`application/json`

curl -X POST "https://example.com/inventory/adjustments" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "product_ids": [      "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22"    ],    "variant_id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31",    "quantity_change": 24,    "type": "restock",    "reason": "Afternoon batch"  }'

{  "success": true,  "message": "Stock adjusted successfully",  "data": {    "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b12",    "type": "restock",    "quantity_before": 12,    "quantity_change": 24,    "quantity_after": 36,    "reason": "Afternoon batch",    "reason_code": null,    "scope": "variant",    "product": {      "id": 20418,      "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22",      "title": "Homemade Chapman",      "slug": "homemade-chapman"    },    "variant": {      "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31",      "title": "50cl",      "option_values": {        "Size": "50cl"      }    },    "order": null,    "shortfall": {      "captured": false,      "quantity": 0    },    "created_at": "2026-09-24T15:30:00+01:00"  }}

200application/json

401application/json

403application/json

429application/json

200application/json

401application/json

403application/json

422application/json

429application/json

200application/json

401application/json

403application/json

409application/json

422application/json

429application/json

200application/json

401application/json

403application/json

404application/json

422application/json

429application/json

200application/json

401application/json

403application/json

422application/json

429application/json

200application/json

401application/json

403application/json

409application/json

422application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`