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 -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/products/ff808181648b61df01648b7000000001/availableItems"

Response

[
  {
    "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 -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/generic/inventoryItem?max=25&offset=0"

# Get a specific inventory item
curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/generic/inventoryItem/inv-001"

Response

{
  "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 \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/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 -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/generic/transaction?max=50&offset=0"

# Get a specific transaction
curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/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 -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/generic/transactionEntry?max=25"

Response

{
  "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 -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/products?max=100")

# Step 2: For each product, fetch availability
curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/products/{product-id}/availableItems"

Known Limitations

• /api/inventoryItems returns 404: The dedicated inventory items list endpoint is not exposed via the REST API. Use /api/generic/inventoryItem or /api/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 sessions: Stock queries return data for the location associated with your current session. To query a different location, authenticate with that location ID.
• Quantity fields: quantityOnHand reflects the total physical stock. quantityAvailable subtracts allocated/reserved quantities. The difference represents stock committed to pending orders or shipments.