Batches API

Batches API

Push Batches

POST /api/v1/integration/batches

Bulk upsert product batches. Each batch must reference a previously synced product by productExternalId.

Required scope: integration:batches:write

Request Body

{
  "batches": [
    {
      "externalId": "string (required)",
      "productExternalId": "string (required)",
      "batchNumber": "string (required in data)",
      "quantity": "number",
      "unit": "string",
      "receivedDate": "string (ISO date)",
      "expiryDate": "string (ISO date)"
    }
  ],
  "autoCreateDDS": false
}

Limits

• Maximum 500 batches per request

Sync Order

Batches depend on products, which optionally depend on suppliers. Sync in this order:

1. Suppliers (via POST /suppliers)
2. Products (via POST /products, optionally with supplierExternalId)
3. Batches (via POST /batches, with productExternalId)

Response

{
  "success": true,
  "created": 1,
  "updated": 0,
  "errors": [],
  "records": [
    { "externalId": "BATCH-001", "internalId": "clx...", "status": "CREATED" }
  ],
  "ddsCreated": []
}

Field Reference

Field	Type	Required	Description
externalId	string	✅	Unique batch ID in your system
productExternalId	string	✅	External ID of the parent product
batchNumber	string	✅	Batch or lot number
quantity	number		Quantity received
unit	string		Unit of measure
receivedDate	string		ISO date when batch was received
expiryDate	string		ISO date for batch expiry

Error: Product Not Found

If a batch references a productExternalId that hasn’t been synced yet, you’ll get:

{
  "externalId": "BATCH-001",
  "error": "Product with externalId \"ITEM-999\" not found. Sync products first."
}

---

List Synced Batches

GET /api/v1/integration/batches

Required scope: integration:batches:read

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	50	Items per page (max 100)
since	string		ISO date filter

Response

Same format as supplier and product listing.