Products API

The Products API lets you manage your product catalog — listing, searching, creating, and updating products in your OpenBoxes instance.

List Products#

Retrieve a paginated list of products. A single q parameter searches across name, product code, description, manufacturer, and vendor fields.

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products?max=10&offset=0"

Query Parameters#

Parameter	Type	Default	Description
max	integer	all	Maximum number of products to return
offset	integer	0	Number of records to skip
q	string	—	Search term matched against name, product code, description, manufacturer, and vendor (partial match)
includeInactive	boolean	false	Include deactivated products

Search Example#

curl -H "X-API-Key: $OB_API_KEY" \
  "https://acme.openboxes.cloud/api/v1/products?q=ibuprofen&max=25"

Response#

List responses are wrapped in a data envelope with a totalCount of all matching products (not just the page returned), so you can paginate with max and offset:

{
  "data": [
    {
      "id": "ff808181648b61df01648b7000000001",
      "productCode": "IBU200",
      "name": "Ibuprofen 200mg",
      "description": "Anti-inflammatory tablet",
      "category": {
        "id": "cat-001",
        "name": "Pharmaceuticals"
      },
      "unitOfMeasure": "EA",
      "dateCreated": "2025-01-15T10:30:00Z",
      "lastUpdated": "2025-03-20T14:22:00Z"
    }
  ],
  "totalCount": 550
}

Get Product by ID#

Retrieve a single product with full details:

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

Response#

{
  "data": {
    "id": "ff808181648b61df01648b7000000001",
    "productCode": "IBU200",
    "name": "Ibuprofen 200mg",
    "description": "Anti-inflammatory tablet",
    "category": {
      "id": "cat-001",
      "name": "Pharmaceuticals"
    },
    "unitOfMeasure": "EA",
    "manufacturer": "PharmaCorp",
    "manufacturerCode": "PC-IBU-200",
    "pricePerUnit": 0.15,
    "coldChain": false,
    "active": true
  }
}

Create Product#

Create a new product in the catalog:

curl -X POST \
  -H "X-API-Key: $OB_API_KEY" \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/api/v1/products" \
  -d '{
    "name": "Amoxicillin 250mg Capsules",
    "productCode": "AMOX250",
    "description": "Antibiotic capsule for oral administration",
    "category": { "id": "cat-001" },
    "unitOfMeasure": "EA",
    "manufacturer": "GenericPharma",
    "coldChain": false
  }'

A successful create returns the new record under a product key ({ "product": { "id": "...", ... } }).

Required Fields#

Field	Type	Description
name	string	Product display name
category	object	Category reference with id

Optional Fields#

Field	Type	Description
productCode	string	Unique product code (auto-generated if omitted)
description	string	Detailed product description
unitOfMeasure	string	Unit of measure (e.g., EA, CS, BX)
manufacturer	string	Manufacturer name
manufacturerCode	string	Manufacturer's product code
coldChain	boolean	Whether product requires cold chain storage
pricePerUnit	number	Default price per unit

Update Product#

The /products endpoint itself does not accept updates. Update an existing product by ID through the generic CRUD API instead:

curl -X PUT \
  -H "X-API-Key: $OB_API_KEY" \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/api/v1/generic/product/ff808181648b61df01648b7000000001" \
  -d '{
    "description": "Anti-inflammatory tablet, 200mg strength",
    "pricePerUnit": 0.18
  }'

Only include the fields you want to update. Omitted fields remain unchanged.

Get Available Items#

Retrieve inventory items (lot/batch records) available for a specific product:

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

Results are scoped to the key owner's current location; pass location.id=<location-id> to query a different one.

Response#

{
  "data": [
    {
      "inventoryItem": {
        "id": "inv-001",
        "lotNumber": "LOT-2025-001",
        "expirationDate": "2026-06-30T00:00:00Z"
      },
      "quantityAvailable": 5000,
      "quantityOnHand": 5200
    }
  ]
}

Product Associations#

Retrieve products associated with a given product (substitutes, equivalents):

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

Important Notes#

• Products are global: Products are not scoped to a specific location or organization. Any product created is visible across all locations within your tenant.
• Category required: Every product must belong to a category. Retrieve available categories via /api/v1/generic/category before creating products.
• Product codes: If you provide a productCode, it must be unique across your entire instance. If omitted, OpenBoxes auto-generates one.
• Deletion: Product deletion is generally not supported if the product has any associated inventory transactions. Deactivate products by setting active: false instead.