Inventory API

The Inventory API provides access to stock levels, inventory items, and transaction history across your warehouse locations.

Current Stock Levels#

Retrieve a snapshot of on-hand quantities for products at a given location. This is typically accessed through the product-level availability endpoint:

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products/ff808181648b61df01648b7000000001/availableItems"

Response#

Responses are wrapped in a data envelope:

{
  "data": [
    {
      "inventoryItem": {
        "id": "inv-001",
        "lotNumber": "LOT-2025-001",
        "expirationDate": "2026-06-30T00:00:00Z",
        "product": {
          "id": "ff808181648b61df01648b7000000001",
          "name": "Ibuprofen 200mg",
          "productCode": "IBU200"
        }
      },
      "binLocation": {
        "id": "bin-A1",
        "name": "Shelf A-1"
      },
      "quantityAvailable": 5000,
      "quantityOnHand": 5200
    }
  ]
}

Inventory Items via Generic API#

Inventory items (lot/batch records) can be accessed through the generic CRUD endpoint:

# List inventory items
curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/generic/inventoryItem?max=25&offset=0"

# Get a specific inventory item
curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/generic/inventoryItem/inv-001"

Response#

Generic endpoints wrap the record (or, for list calls, the array of records) in a data envelope:

{
  "data": {
    "id": "inv-001",
    "lotNumber": "LOT-2025-001",
    "expirationDate": "2026-06-30T00:00:00Z",
    "product": {
      "id": "ff808181648b61df01648b7000000001",
      "name": "Ibuprofen 200mg"
    },
    "dateCreated": "2025-01-10T08:00:00Z",
    "lastUpdated": "2025-03-15T12:30:00Z"
  }
}

Create Inventory Item#

Create a new lot/batch record for a product:

curl -X POST \
  -H "X-API-Key: $OB_API_KEY" \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/api/v1/generic/inventoryItem" \
  -d '{
    "product": { "id": "ff808181648b61df01648b7000000001" },
    "lotNumber": "LOT-2025-042",
    "expirationDate": "2027-01-31T00:00:00Z"
  }'

Fields#

Field	Type	Required	Description
product	object	Yes	Product reference with id
lotNumber	string	No	Lot or batch number
expirationDate	string	No	Expiration date in ISO 8601 format

Inventory Transactions#

Inventory transactions record stock changes (receipts, issues, adjustments, transfers). Access them through the generic API:

# List transactions
curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/generic/transaction?max=50&offset=0"

# Get a specific transaction
curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/generic/transaction/txn-001"

Transaction Types#

Type	Description
CREDIT	Stock received into inventory
DEBIT	Stock issued or consumed
TRANSFER_IN	Stock transferred in from another location
TRANSFER_OUT	Stock transferred out to another location
ADJUSTMENT	Manual inventory adjustment (positive or negative)
INVENTORY	Physical inventory count

Transaction Entries#

Each transaction contains entries that specify the product, lot, and quantity affected:

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/generic/transactionEntry?max=25"

Response#

{
  "data": [
    {
      "id": "entry-001",
      "quantity": 500,
      "inventoryItem": {
        "id": "inv-001",
        "lotNumber": "LOT-2025-001"
      },
      "transaction": {
        "id": "txn-001",
        "transactionType": { "name": "CREDIT" }
      },
      "binLocation": {
        "id": "bin-A1",
        "name": "Shelf A-1"
      }
    }
  ]
}

Stock Level Summary#

To get a high-level stock summary across products, combine the available items data with product listings. A common pattern is to iterate over products and fetch availability for each:

# Step 1: Get product IDs
products=$(curl -s -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products?max=100")

# Step 2: For each product, fetch availability
curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products/{product-id}/availableItems"

Known Limitations#

• /api/v1/inventoryItems returns 404: The dedicated inventory items list endpoint is not exposed via the REST API. Use /api/v1/generic/inventoryItem or /api/v1/products/{id}/availableItems instead.
• No bulk stock query: There is no single endpoint to retrieve stock levels across all products. You must query per-product or use the generic transaction endpoints to reconstruct quantities.
• Location-bound results: Stock queries return data for the current location: the Default location on the key owner's user record, or the only depot they have access to (see Locations for the exact rule). To query a different location, pass an explicit location parameter where supported, or change the key owner's Default location (Configuration ▸ Users ▸ edit). Calling availableItems without location.id when the key owner has no current location returns an error.
• Quantity fields: quantityOnHand reflects the total physical stock. quantityAvailable subtracts allocated/reserved quantities. The difference represents stock committed to pending orders or shipments.