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. Supports search by name or product code.

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/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
name	string	--	Filter by product name (partial match)
productCode	string	--	Filter by product code

Search Example

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/products?name=ibuprofen&max=25"

Response

[
  {
    "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"
  }
]

Get Product by ID

Retrieve a single product with full details:

curl -b cookies.txt \
  "https://acme.openboxes.cloud/openboxes/api/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 \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/products" \
  -d '{
    "name": "Amoxicillin 250mg Capsules",
    "productCode": "AMOX250",
    "description": "Antibiotic capsule for oral administration",
    "category": { "id": "cat-001" },
    "unitOfMeasure": "EA",
    "manufacturer": "GenericPharma",
    "coldChain": false
  }'

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

Update an existing product by ID:

curl -X PUT \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  "https://acme.openboxes.cloud/openboxes/api/products/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 -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"
    },
    "quantityAvailable": 5000,
    "quantityOnHand": 5200
  }
]

Product Associations

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

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