Products
| Route | Scope | What it does |
|---|---|---|
GET /v1/products | read | lists products |
GET /v1/products/{id} | read | shows a product (with photo and, if asked, its batches) |
POST /v1/products | write | creates a product |
PATCH /v1/products/{id} | write | updates a product |
DELETE /v1/products/{id} | delete | deletes a product and all its batches |
The batches of a product have their own routes: see Batches.
The product
| Field | Type | Description |
|---|---|---|
id | UUID | identifier |
name | text | product name |
code | text or null | barcode (EAN/GTIN) or internal code |
days_to_be_next | number or null | how many days before expiry a batch counts as "expiring soon" |
brand_id | UUID or null | brand |
category_id | UUID or null | category |
store_id | UUID or null | store |
has_image | yes/no | whether the product has a photo |
created_at, updated_at | date-time | creation and last change |
List: GET /v1/products
| Parameter | Description |
|---|---|
q | search in the name or code (contains the text, case-insensitive) |
code | exact code |
brand_id, category_id, store_id | only products of that brand, category or store |
updated_since | only those created or changed since that instant |
limit, cursor | pagination |
curl "https://api.validades.com/v1/products?code=7891000100103" \
-H "Authorization: Bearer vld_live_YOUR_KEY"
Get: GET /v1/products/{id}
The response also has:
| Field | Description |
|---|---|
image_url | temporary link to the product photo (valid for a few minutes), or null |
batches | only with include=batches: up to 500 batches, sorted by expiry date |
batches_truncated | only with include=batches: true if the product has more than 500 batches |
curl "https://api.validades.com/v1/products/PRODUCT_ID?include=batches" \
-H "Authorization: Bearer vld_live_YOUR_KEY"
Without include, the response has the ETag header and accepts If-None-Match. See Concurrency and idempotency.
Create: POST /v1/products
| Field | Required | Rules |
|---|---|---|
name | yes | 1 to 255 characters |
code | no | up to 100 characters |
days_to_be_next | no | integer from 0 to 3650 |
brand_id, category_id | no | must exist in the organization |
store_id | no | must exist in the organization and be active |
id | no | UUID you generate; if it already exists, the response is 409 conflict |
curl -X POST https://api.validades.com/v1/products \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: product-7891000100103" \
-d '{"name": "Whole milk 1L", "code": "7891000100103", "days_to_be_next": 15, "category_id": "CATEGORY_ID"}'
201 response with { "data": { …product… } } and the ETag header.
Update: PATCH /v1/products/{id}
Send only the fields you want to change (at least one). null clears a field, except name, which cannot be empty.
curl -X PATCH https://api.validades.com/v1/products/PRODUCT_ID \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"days_to_be_next": 7, "brand_id": null}'
200 response with the updated product. Accepts If-Match.
Delete: DELETE /v1/products/{id}
Also deletes the batches
Deleting a product deletes all its batches and the photo, on every device of the organization. The deletion is permanent.
{
"data": {
"id": "6b7e1f0a-…",
"deleted": { "product": 1, "batches": 3 }
}
}
Accepts If-Match.