Inventory API

Read inventory levels and the underlying stock movements for the products on your account. One row per product variant, optionally scoped to a single warehouse.

#Endpoints

• GET /v1/inventory/list — list inventory items with paging and filters.

#Authentication

Standard Bearer auth — see Authentication and API keys.

#List inventory

GET /v1/inventory/list

Query parameters:

• page (integer, default 1) — page number, 1-indexed.
• page_size (integer, default 20, max 100) — items per page.
• sort_by (string, default createdAt) — field to sort by.
• sort_direction (string, default ASC) — ASC or DESC.
• warehouse_id (string, optional) — restrict results to a single warehouse.
• product_name (string, optional) — partial-match filter on product title.
• sku (string, optional) — partial-match filter on variant SKU.
• status (string, optional) — IN_STOCK, LOW_STOCK, or OUT_OF_STOCK. Note: the filter takes uppercase values, but the value returned in each item's status field is lowercase. See the callout below.

#Response shape

{
  "items": [ { "...": "see below" } ],
  "pagination": {
    "total_count": 142,
    "page": 1,
    "page_size": 20,
    "has_more": true
  }
}

#Item fields

Each entry in items has:

• id — the inventory row id (one per variant, per account).
• product_id — the product id this variant belongs to.
• product_name — the product title.
• sku — the variant SKU.
• account — { id, company, status, customer_type } — the account that owns the inventory.
• status — lowercase string: in_stock, low_stock, or out_of_stock. Note the case: the query filter accepts IN_STOCK etc. (uppercase), but the value emitted on each item is lowercase.
• on_hand — total physical units in the warehouse.
• available — units that can be allocated to a new order (on_hand minus reservations).
• allocated — units already reserved against open orders.
• inbound — units expected to arrive at the warehouse.
• warehouse — { warehouse_id, warehouse_name, quantity }. Optional — omitted when the row is not scoped to a single warehouse.
• inventory_events — array of stock movements that affected this row. See below.

#inventory_events

Each event is a row from the stock-movement ledger:

• id — event id.
• product_id — product the event applies to.
• event_type — what kind of movement (lowercase string, e.g. shipment, adjustment, return).
• quantity — signed integer; positive means stock went up, negative means stock went down.
• timestamp — ISO 8601 timestamp.
• description — optional human-readable note.
• order_id — optional. Set when the movement was driven by an order.
• account_id — optional. The account that triggered the movement.
• variant_sku — optional. The variant the event applied to.
• attributes — optional { color, size, material, style } describing the variant.
• warehouse_id — optional. The warehouse the movement affected.
• order_number — optional. Set when order_id is set.

#Errors

• 401 Unauthorized — missing, malformed, or invalid bearer token. See Authentication and API keys.
• 500 Internal Server Error — unexpected error. Body is { "message": "..." }.

#Example

Request:

curl -X GET 'https://api.merch.com/v1/inventory/list?page=1&page_size=20&status=LOW_STOCK' \
  -H 'Authorization: Bearer <your_api_key>'

Response:

{
  "items": [
    {
      "id": "<inventory_row_id>",
      "product_id": "<product_id>",
      "product_name": "Logo Tee",
      "sku": "TEE-BLK-M",
      "account": {
        "id": "<account_id>",
        "company": "Acme Inc",
        "status": "active",
        "customer_type": "merch_account"
      },
      "status": "low_stock",
      "on_hand": 18,
      "available": 12,
      "allocated": 6,
      "inbound": 200,
      "warehouse": {
        "warehouse_id": "<warehouse_id>",
        "warehouse_name": "US East",
        "quantity": 18
      },
      "inventory_events": [
        {
          "id": "<event_id>",
          "product_id": "<product_id>",
          "event_type": "shipment",
          "quantity": -1,
          "timestamp": "2026-05-07T17:14:22.000Z",
          "description": "Shipped to recipient",
          "order_id": "<order_id>",
          "order_number": "ORD-12345",
          "account_id": "<account_id>",
          "variant_sku": "TEE-BLK-M",
          "attributes": { "color": "Black", "size": "M" },
          "warehouse_id": "<warehouse_id>"
        }
      ]
    }
  ],
  "pagination": {
    "total_count": 142,
    "page": 1,
    "page_size": 20,
    "has_more": true
  }
}