Inventory API

The Inventory API enables you to query product catalog data and real-time stock levels for your business. Use it to check availability before creating orders or to sync stock data with external systems.

Overview

• List Inventory: Retrieve all products with optional search filtering
• Get Single Item: Look up a specific inventory item by ID
• Declare On-Hand Quantity: Set the absolute stock level for a SKU (requires inventory:write)
• Upsert and Archive Catalog Items: Create, update or archive catalog items by SKU without touching stock (requires inventory:write)

Authentication

Both inventory endpoints require:

• Scope: inventory:read
• Auth Method: OAuth 2.0 M2M (Machine-to-Machine)
• Format: Bearer token in Authorization header

See the Authentication guide for how to obtain a JWT token with the inventory:read scope.

List Inventory

Retrieve a list of all active inventory items for your business.

Request

GET /e9v3/inventory?search=<query>&limit=100
Authorization: Bearer <jwt-token>

Query Parameters

Response (200 OK)

{
  "success": true,
  "inventory": [
    {
      "itemId": "inv_a1b2c3d4",
      "businessId": "biz-456",
      "sku": "WIDGET-001",
      "productName": "Premium Widget",
      "description": "High-quality widget for industrial use",
      "category": "Widgets",
      "brand": "Acme",
      "barcode": "9781234567890",
      "imageUrl": "https://storage.example.com/widget-001.jpg",
      "availableQuantity": 150,
      "totalQuantity": 200,
      "reservedQuantity": 30,
      "orderedQuantity": 20,
      "returnsQuantity": 0,
      "unitOfMeasure": "pcs",
      "isActive": true,
      "isComposite": false,
      "stockStatus": "inStock"
    }
  ],
  "count": 1,
  "hasMore": false
}

Response Fields

List-level paging fields (additive — existing clients that ignore unknown JSON keys are unchanged):

Paging: limit is a page size (max 500), not a cap on the catalog. Existing GET /e9v3/inventory?limit=100 (or ?search=&limit=) calls still return the first page with success, inventory, and count. To dump the whole catalog, loop while hasMore is true and pass nextCursor as cursor.

Data source: list and search both read the versioned InventoryIndex (quantities as of the last IndexRegenerate). Variant SKUs appear as extra rows with itemId of the parent product. Get-by-id reads the live Inventory document. Inactive items (isActive: false) are silently excluded from the list endpoint. If no index is published, list returns 404 with "Inventory index not published".

Stock Status Logic

Get Single Item

Look up a specific inventory item by its ID. This reads the live Inventory document (not the versioned index).

Request

GET /e9v3/inventory/:itemId
Authorization: Bearer <jwt-token>

Response (200 OK)

{
  "success": true,
  "inventory": [
    {
      "itemId": "inv_a1b2c3d4",
      "sku": "WIDGET-001",
      "productName": "Premium Widget",
      "availableQuantity": 150,
      "totalQuantity": 200,
      "stockStatus": "inStock"
    }
  ],
  "count": 1
}

Response (404 Not Found)

{
  "success": false,
  "error": "Inventory item not found"
}

Declare On-Hand Quantity

Set (not adjust) the absolute on-hand quantity for a SKU. This is applied through the platform’s transactional inventory pipeline as an asynchronous job and returns a jobId — poll GET /e9v3/jobs/:jobId for the outcome. Requires the inventory:write scope.

Request

POST /e9v3/inventory/sync
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "sku": "WIDGET-001",
  "quantity": 200,
  "sourceRecordId": "stocktake-2024-01-15"
}

Response (200 OK)

{
  "success": true,
  "jobId": "inventory_1776400267719207348"
}

Notes:

• quantity is the new absolute on-hand count, not a delta.
• Unlike the order writes, this endpoint validates the SKU — an unknown SKU returns 404.
• Retries with the same sourceRecordId are deduplicated via a deterministic job id.

See the Endpoints reference for the full schema.

Upsert and Archive Catalog Items

Create, update or archive catalog items by SKU, for example to keep a storefront’s product list in step. These routes change item metadata only: stock quantities are never changed. Requires the inventory:write scope.

Request

POST /e9v3/inventory/items
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "sku": "WIDGET-001",
  "name": "Widget",
  "barcode": "9300000000001",
  "weightGrams": 250,
  "active": true,
  "sourceRecordId": "shopify:my-shop:variant:42"
}

Notes:

• sku is required, up to 256 characters.
• Upserts with the same sourceRecordId and SKU are idempotent. A SKU already owned by a different sourceRecordId returns 409.
• active: false archives the item, the same as the archive route.

Common Use Cases

Check stock before creating an order

# 1. Search for the product by SKU
curl -X GET 'https://api.equos.one/e9v3/inventory?search=WIDGET-001' \
  -H 'Authorization: Bearer <jwt-token>'

# 2. Verify availableQuantity >= order quantity
# 3. Create the order if stock is sufficient
curl -X POST 'https://api.equos.one/e9v3/orders/send' \
  -H 'Authorization: Bearer <jwt-token>' \
  -H 'Content-Type: application/json' \
  -d '{"customerId": "cust-123", "items": [{"sku": "WIDGET-001", "productName": "Premium Widget", "quantity": 5}]}'

Sync stock levels to an external system

# First page (same call existing integrations already make)
curl -X GET 'https://api.equos.one/e9v3/inventory?limit=500' \
  -H 'Authorization: Bearer <jwt-token>'

# Following pages: repeat until hasMore is false
curl -X GET 'https://api.equos.one/e9v3/inventory?limit=500&cursor=<nextCursor>' \
  -H 'Authorization: Bearer <jwt-token>'

Filter by category

curl -X GET 'https://api.equos.one/e9v3/inventory?search=Electronics&limit=50' \
  -H 'Authorization: Bearer <jwt-token>'

Error Handling

Next Steps

• Create Orders using item SKUs from the inventory
• API Tester to try inventory queries interactively
• Webhooks to receive notifications when stock levels change