Batches
A batch is a quantity of a product with an expiry date.
| Route | Scope | What it does |
|---|---|---|
GET /v1/batches | read | lists batches |
GET /v1/batches/{id} | read | shows a batch |
GET /v1/products/{id}/batches | read | lists the batches of a product |
POST /v1/batches | write | creates a batch (product in the body) |
POST /v1/products/{id}/batches | write | creates a batch for the product in the URL |
PATCH /v1/batches/{id} | write | updates a batch |
DELETE /v1/batches/{id} | delete | deletes a batch |
The batch
| Field | Type | Description |
|---|---|---|
id | UUID | identifier |
product_id | UUID | product of the batch |
name | text | batch name or number |
exp_date | date (YYYY-MM-DD) | expiry date |
amount | number or null | quantity |
unit | text or null | unit (for example un, kg) |
price | number or null | sale price |
cost_price | number or null | cost price |
status | checked or unchecked | whether the batch was already checked |
location | text or null | where the batch is (aisle, shelf…) |
additional_data | text or null | notes |
created_at, updated_at | date-time | creation and last change |
List: GET /v1/batches
| Parameter | Description |
|---|---|
exp_date_from | expiry on or after this date (YYYY-MM-DD) |
exp_date_to | expiry on or before this date (YYYY-MM-DD) |
status | checked or unchecked |
product_id | only the batches of that product |
store_id | only the batches of products of that store |
updated_since | only those created or changed since that instant |
limit, cursor | pagination |
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
| Field | Required | Rules |
|---|---|---|
product_id | yes on /v1/batches | product of the organization. On /v1/products/{id}/batches it comes from the URL |
exp_date | yes | valid YYYY-MM-DD date |
name | no | up to 100 characters. If not sent, the batch gets the next number ("1", "2"…) among the product's batches |
amount | no | from 0 to 1,000,000,000 |
unit | no | up to 20 characters |
price, cost_price | no | from 0 to 99,999,999.99 |
status | no | checked or unchecked (default unchecked) |
location | no | up to 255 characters |
additional_data | no | up to 1000 characters |
id | no | UUID 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.