Admin Inventory API — Manage Stock Levels and Reservations

The Admin Inventory API lets you inspect real-time stock levels for any product variant and make surgical adjustments without touching pending order allocations. The system tracks stock using a reservation model: units move through distinct states as orders are placed, confirmed, shipped, and fulfilled. Understanding which state each unit is in is essential before issuing any manual adjustment.

All endpoints under /admin/inventory require an authenticated session with the ADMIN or SUPER_ADMIN role. For every PATCH request, first call GET /auth/csrf-token and pass the returned token in the x-csrf-token header.

The Reservation Model

Every inventory record tracks three quantities that together describe the full stock picture for a variant.

Field	Description
`quantity_on_hand`	Total physical units in your warehouse — the absolute ceiling for all allocations.
`quantity_reserved`	Units held by pending or unconfirmed orders. Not yet committed; can be released if those orders are cancelled.
`quantity_available`	Units free for new orders: `quantity_on_hand − quantity_reserved`.

The stock_status field is derived automatically from quantity_available and the variant’s reorder_level:

IN_STOCK — quantity_available is above the reorder threshold (or no threshold is set)
LOW_STOCK — quantity_available is at or below the reorder threshold
OUT_OF_STOCK — quantity_available is zero or negative

Inventory transitions by order status

Order Status Transition	Inventory Effect
Customer places order → `pending`	`quantity_reserved` increases by order quantity
`pending` → `confirmed`	No change — units remain reserved
`confirmed` → `processing`	No change — units remain reserved
`processing` → `shipped`	No change — units remain reserved until delivery
`shipped` → `delivered`	`quantity_reserved` decreases; units are considered fulfilled
Any status → `cancelled`	Reserved units are released back to `quantity_available`
`delivered` → `returned`	`quantity_on_hand` increases to reflect returned stock

Get Inventory for a Variant

Retrieve the full inventory record for a single variant, including all quantity breakdowns, reorder level, stock status, and the timestamp of the last stock movement.

GET /admin/inventory/{variant_public_id}

Path Parameters

string

required

The variant’s public ID. Must start with var_.

Response

boolean

Always true on a 200 response.

object

The inventory record for the requested variant.

Show Inventory record fields

string

Variant identifier, prefixed var_.

string

The variant’s stock-keeping unit code.

string

Display name of the parent product.

integer

Total physical units in stock (≥ 0).

integer

Units held by pending orders (≥ 0).

integer

Units free for new orders: on_hand − reserved (≥ 0).

integer | null

Threshold below which stock_status becomes LOW_STOCK. null if not configured.

string

Computed status: IN_STOCK, LOW_STOCK, or OUT_OF_STOCK.

string | null

ISO 8601 UTC timestamp of the most recent stock movement, or null if never updated.

Example — get inventory for a variant

curl https://api.example.com/api/v1/admin/inventory/var_01HXYZ \
  -H "Cookie: session=<your-session-cookie>"

200 Response

{
  "success": true,
  "data": {
    "variant_public_id": "var_01HXYZ",
    "sku": "TSHIRT-BLK-M",
    "product_name": "Classic Cotton T-Shirt",
    "quantity_on_hand": 150,
    "quantity_reserved": 12,
    "quantity_available": 138,
    "reorder_level": 20,
    "stock_status": "IN_STOCK",
    "last_stock_update": "2024-06-15T09:22:00.000Z"
  }
}

List Inventory

Retrieve a paginated list of inventory records across all variants. Filter by stock status, search by product name or SKU, and sort by any tracked quantity.

GET /admin/inventory

Query Parameters

integer

default:"1"

Page number (1-based).

integer

default:"20"

Results per page. Range: 1–100.

string

Free-text search across product name and SKU.

string

Filter by computed stock status. Accepted values: IN_STOCK, LOW_STOCK, OUT_OF_STOCK.

string

default:"false"

Pass "true" to include records for soft-deleted variants.

string

default:"product_name"

Sort field. Prefix with - for descending. Accepted values: product_name, -product_name, sku, -sku, quantity_on_hand, -quantity_on_hand, quantity_available, -quantity_available, last_stock_update, -last_stock_update.

Use stock_status=LOW_STOCK combined with sort=-quantity_available to surface the variants closest to going out of stock — ideal for daily reorder reviews.

Create Inventory Record

Create an inventory record for a variant. Each variant can have at most one inventory record — if one already exists, the API returns 409 Conflict. Call this endpoint after adding a new variant before it can be made available for purchase.

POST /admin/inventory

Request Body

string

required

The variant’s public ID, prefixed var_. The variant must exist and must not already have an inventory record.

integer

required

Initial on-hand stock count (≥ 0).

integer

Optional reorder threshold. When quantity_available falls to or below this value, stock_status becomes LOW_STOCK. Must be ≥ 0.

Example

CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X POST https://api.example.com/api/v1/admin/inventory \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "variant_public_id": "var_01HXYZ",
    "quantity_on_hand": 100,
    "reorder_level": 10
  }'

const response = await fetch('https://api.example.com/api/v1/admin/inventory', {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Content-Type': 'application/json',
    'x-csrf-token': csrfToken,
  },
  body: JSON.stringify({
    variant_public_id: 'var_01HXYZ',
    quantity_on_hand: 100,
    reorder_level: 10,
  }),
});

Error Responses

Status	Meaning
`400`	Validation error — missing required field or invalid value.
`401`	No active session.
`403`	Insufficient role.
`409`	An inventory record already exists for this variant.

Adjust Stock Level

Set an absolute stock level or apply a delta to quantity_on_hand for a variant. Use this endpoint after physical inventory counts, receiving new shipments, or writing off damaged goods.

PATCH /admin/inventory/{variant_public_id}

Path Parameters

string

required

The variant’s public ID. Must start with var_.

Request Body

Provide either quantity_on_hand (absolute set) or quantity_change (delta). The two fields are mutually exclusive. At least one field is required.

integer

Set the on-hand quantity to this exact value (≥ 0). Mutually exclusive with quantity_change.

integer

Apply a non-zero delta to the current on-hand quantity. Use a negative value to reduce stock (e.g. -5 for five damaged units). Mutually exclusive with quantity_on_hand.

integer | null

Update the reorder threshold. Pass null to remove the threshold entirely.

string

Human-readable reason for the adjustment, stored in the audit log. Maximum 255 characters.

# First get a CSRF token
CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

# Then adjust inventory
curl -X PATCH https://api.example.com/api/v1/admin/inventory/var_01HXYZ \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity_on_hand": 200,
    "reorder_level": 25,
    "reason": "Physical cycle count — 2024-06-15"
  }'

CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X PATCH https://api.example.com/api/v1/admin/inventory/var_01HXYZ \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity_change": -5,
    "reason": "Water damage — warehouse incident 2024-06-15"
  }'

200 Response

{
  "success": true,
  "data": {
    "variant_public_id": "var_01HXYZ",
    "sku": "TSHIRT-BLK-M",
    "product_name": "Classic Cotton T-Shirt",
    "quantity_on_hand": 200,
    "quantity_reserved": 12,
    "quantity_available": 180,
    "reorder_level": 25,
    "stock_status": "IN_STOCK",
    "last_stock_update": "2024-06-15T10:05:00.000Z"
  }
}

Reserve or Release Stock Manually

Adjust the quantity_reserved counter for a variant using a signed delta. A positive change reserves additional units; a negative change releases them back to quantity_available. Both operations are validated against current stock levels to prevent over-reservation.

PATCH /admin/inventory/{variant_public_id}/reserve

The checkout flow automatically reserves stock when a customer places an order and releases it if the order is cancelled. Use this endpoint only for exceptional cases — for example, holding units for a photoshoot, a VIP customer pre-order, or correcting a reservation discrepancy caused by a failed webhook.

Path Parameters

string

required

The variant’s public ID. Must start with var_.

Request Body

integer

required

Non-zero delta applied to quantity_reserved. Positive to reserve; negative to release. The API rejects a request if the resulting quantity_available would drop below zero.

string

Human-readable reason stored in the audit log. Maximum 255 characters.

CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X PATCH https://api.example.com/api/v1/admin/inventory/var_01HXYZ/reserve \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "change": 5,
    "reason": "Held for studio photoshoot — returns 2024-06-20"
  }'

CSRF=$(curl -s https://api.example.com/api/v1/auth/csrf-token \
  -H "Cookie: session=<your-session-cookie>" | jq -r '.data.csrf_token')

curl -X PATCH https://api.example.com/api/v1/admin/inventory/var_01HXYZ/reserve \
  -H "Cookie: session=<your-session-cookie>" \
  -H "x-csrf-token: $CSRF" \
  -H "Content-Type: application/json" \
  -d '{
    "change": -5,
    "reason": "Photoshoot complete — units returned to available stock"
  }'

200 Response

{
  "success": true,
  "data": {
    "variant_public_id": "var_01HXYZ",
    "sku": "TSHIRT-BLK-M",
    "quantity_on_hand": 200,
    "quantity_reserved": 17,
    "quantity_available": 183,
    "stock_status": "IN_STOCK",
    "last_stock_update": "2024-06-15T11:00:00.000Z"
  }
}

Passing a change value that would push quantity_available below zero returns a 400 Bad Request. Always fetch the current inventory record first to verify you have sufficient available stock before reserving.

Catalog Management

Operations

Users & Moderation

Analytics & Audit

Admin Inventory API — Manage Stock Levels and Reservations

The Reservation Model

Get Inventory for a Variant

Path Parameters

Response

List Inventory

Query Parameters

Create Inventory Record

Request Body

Example

Error Responses

Adjust Stock Level

Path Parameters

Request Body

Reserve or Release Stock Manually

Path Parameters

Request Body

​The Reservation Model

​Get Inventory for a Variant

​Path Parameters

​Response

​List Inventory

​Query Parameters

​Create Inventory Record

​Request Body

​Example

​Error Responses

​Adjust Stock Level

​Path Parameters

​Request Body

​Reserve or Release Stock Manually

​Path Parameters

​Request Body

The Reservation Model

Get Inventory for a Variant

Path Parameters

Response

List Inventory

Query Parameters

Create Inventory Record

Request Body

Example

Error Responses

Adjust Stock Level

Path Parameters

Request Body

Reserve or Release Stock Manually

Path Parameters

Request Body