Skip to main content

Batches

A batch is a quantity of a product with an expiry date.

RouteScopeWhat it does
GET /v1/batchesreadlists batches
GET /v1/batches/{id}readshows a batch
GET /v1/products/{id}/batchesreadlists the batches of a product
POST /v1/batcheswritecreates a batch (product in the body)
POST /v1/products/{id}/batcheswritecreates a batch for the product in the URL
PATCH /v1/batches/{id}writeupdates a batch
DELETE /v1/batches/{id}deletedeletes a batch

The batch​

FieldTypeDescription
idUUIDidentifier
product_idUUIDproduct of the batch
nametextbatch name or number
exp_datedate (YYYY-MM-DD)expiry date
amountnumber or nullquantity
unittext or nullunit (for example un, kg)
pricenumber or nullsale price
cost_pricenumber or nullcost price
statuschecked or uncheckedwhether the batch was already checked
locationtext or nullwhere the batch is (aisle, shelf…)
additional_datatext or nullnotes
created_at, updated_atdate-timecreation and last change

List: GET /v1/batches​

ParameterDescription
exp_date_fromexpiry on or after this date (YYYY-MM-DD)
exp_date_toexpiry on or before this date (YYYY-MM-DD)
statuschecked or unchecked
product_idonly the batches of that product
store_idonly the batches of products of that store
updated_sinceonly those created or changed since that instant
limit, cursorpagination

Batches expiring in the next 7 days that were not checked yet:

curl "https://api.validades.com/v1/batches?exp_date_from=2026-11-07&exp_date_to=2026-11-14&status=unchecked&limit=100" \
-H "Authorization: Bearer vld_live_YOUR_KEY"

The list is sorted by last change, not by expiry date. To sort by expiry, sort in your system or use GET /v1/products/{id}?include=batches, which returns the batches of a product sorted by expiry date.

GET /v1/products/{id}/batches accepts the same filters and answers 404 if the product does not exist.

Create: POST /v1/batches or POST /v1/products/{id}/batches​

FieldRequiredRules
product_idyes on /v1/batchesproduct of the organization. On /v1/products/{id}/batches it comes from the URL
exp_dateyesvalid YYYY-MM-DD date
namenoup to 100 characters. If not sent, the batch gets the next number ("1", "2"…) among the product's batches
amountnofrom 0 to 1,000,000,000
unitnoup to 20 characters
price, cost_pricenofrom 0 to 99,999,999.99
statusnochecked or unchecked (default unchecked)
locationnoup to 255 characters
additional_datanoup to 1000 characters
idnoUUID you generate; if it already exists, the response is 409 conflict
curl -X POST https://api.validades.com/v1/products/PRODUCT_ID/batches \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: invoice-4521-item-3" \
-d '{"exp_date": "2026-12-31", "amount": 24, "unit": "un", "price": 6.49, "location": "Aisle 3"}'

201 response with { "data": { …batch… } } and the ETag header.

Update: PATCH /v1/batches/{id}​

Send only the fields you want to change (at least one). null clears a field. The product of the batch (product_id) cannot be changed: create a new batch on the other product.

curl -X PATCH https://api.validades.com/v1/batches/BATCH_ID \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 10, "status": "checked"}'

Accepts If-Match.

Delete: DELETE /v1/batches/{id}​

{ "data": { "id": "…", "deleted": { "batch": 1 } } }

Accepts If-Match.