> ## Documentation Index
> Fetch the complete documentation index at: https://codebyahmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Inventory API — Manage Stock Levels and Reservations

> View and adjust per-variant stock levels. The inventory system uses reservation semantics — stock can be reserved, committed, or released as orders progress.

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.

<Note>
  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.
</Note>

***

## 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

<Info>
  **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        |
</Info>

***

## 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

<ParamField path="variant_public_id" type="string" required>
  The variant's public ID. Must start with `var_`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Always `true` on a 200 response.
</ResponseField>

<ResponseField name="data" type="object">
  The inventory record for the requested variant.

  <Expandable title="Inventory record fields">
    <ResponseField name="variant_public_id" type="string">
      Variant identifier, prefixed `var_`.
    </ResponseField>

    <ResponseField name="sku" type="string">
      The variant's stock-keeping unit code.
    </ResponseField>

    <ResponseField name="product_name" type="string">
      Display name of the parent product.
    </ResponseField>

    <ResponseField name="quantity_on_hand" type="integer">
      Total physical units in stock (≥ 0).
    </ResponseField>

    <ResponseField name="quantity_reserved" type="integer">
      Units held by pending orders (≥ 0).
    </ResponseField>

    <ResponseField name="quantity_available" type="integer">
      Units free for new orders: `on_hand − reserved` (≥ 0).
    </ResponseField>

    <ResponseField name="reorder_level" type="integer | null">
      Threshold below which `stock_status` becomes `LOW_STOCK`. `null` if not configured.
    </ResponseField>

    <ResponseField name="stock_status" type="string">
      Computed status: `IN_STOCK`, `LOW_STOCK`, or `OUT_OF_STOCK`.
    </ResponseField>

    <ResponseField name="last_stock_update" type="string | null">
      ISO 8601 UTC timestamp of the most recent stock movement, or `null` if never updated.
    </ResponseField>
  </Expandable>
</ResponseField>

```bash Example — get inventory for a variant theme={null}
curl https://api.example.com/api/v1/admin/inventory/var_01HXYZ \
  -H "Cookie: session=<your-session-cookie>"
```

```json 200 Response theme={null}
{
  "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

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Results per page. Range: 1–100.
</ParamField>

<ParamField query="search" type="string">
  Free-text search across product name and SKU.
</ParamField>

<ParamField query="stock_status" type="string">
  Filter by computed stock status. Accepted values: `IN_STOCK`, `LOW_STOCK`, `OUT_OF_STOCK`.
</ParamField>

<ParamField query="include_deleted" type="string" default="false">
  Pass `"true"` to include records for soft-deleted variants.
</ParamField>

<ParamField query="sort" type="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`.
</ParamField>

<Tip>
  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.
</Tip>

***

## 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

<ParamField body="variant_public_id" type="string" required>
  The variant's public ID, prefixed `var_`. The variant must exist and must not already have an inventory record.
</ParamField>

<ParamField body="quantity_on_hand" type="integer" required>
  Initial on-hand stock count (≥ 0).
</ParamField>

<ParamField body="reorder_level" type="integer">
  Optional reorder threshold. When `quantity_available` falls to or below this value, `stock_status` becomes `LOW_STOCK`. Must be ≥ 0.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Node.js theme={null}
  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,
    }),
  });
  ```
</CodeGroup>

### 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

<ParamField path="variant_public_id" type="string" required>
  The variant's public ID. Must start with `var_`.
</ParamField>

### 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.

<ParamField body="quantity_on_hand" type="integer">
  Set the on-hand quantity to this exact value (≥ 0). Mutually exclusive with `quantity_change`.
</ParamField>

<ParamField body="quantity_change" type="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`.
</ParamField>

<ParamField body="reorder_level" type="integer | null">
  Update the reorder threshold. Pass `null` to remove the threshold entirely.
</ParamField>

<ParamField body="reason" type="string">
  Human-readable reason for the adjustment, stored in the audit log. Maximum 255 characters.
</ParamField>

<CodeGroup>
  ```bash Absolute set (cycle count) theme={null}
  # 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"
    }'
  ```

  ```bash Delta adjustment (damaged goods write-off) theme={null}
  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"
    }'
  ```
</CodeGroup>

```json 200 Response theme={null}
{
  "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
```

<Note>
  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.
</Note>

### Path Parameters

<ParamField path="variant_public_id" type="string" required>
  The variant's public ID. Must start with `var_`.
</ParamField>

### Request Body

<ParamField body="change" type="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.
</ParamField>

<ParamField body="reason" type="string">
  Human-readable reason stored in the audit log. Maximum 255 characters.
</ParamField>

<CodeGroup>
  ```bash Reserve 5 units theme={null}
  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"
    }'
  ```

  ```bash Release 5 units theme={null}
  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"
    }'
  ```
</CodeGroup>

```json 200 Response theme={null}
{
  "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"
  }
}
```

<Warning>
  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.
</Warning>