Skip to main content

Products

RouteScopeWhat it does
GET /v1/productsreadlists products
GET /v1/products/{id}readshows a product (with photo and, if asked, its batches)
POST /v1/productswritecreates a product
PATCH /v1/products/{id}writeupdates a product
DELETE /v1/products/{id}deletedeletes a product and all its batches

The batches of a product have their own routes: see Batches.

The product​

FieldTypeDescription
idUUIDidentifier
nametextproduct name
codetext or nullbarcode (EAN/GTIN) or internal code
days_to_be_nextnumber or nullhow many days before expiry a batch counts as "expiring soon"
brand_idUUID or nullbrand
category_idUUID or nullcategory
store_idUUID or nullstore
has_imageyes/nowhether the product has a photo
created_at, updated_atdate-timecreation and last change

List: GET /v1/products​

ParameterDescription
qsearch in the name or code (contains the text, case-insensitive)
codeexact code
brand_id, category_id, store_idonly products of that brand, category or store
updated_sinceonly those created or changed since that instant
limit, cursorpagination
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:

FieldDescription
image_urltemporary link to the product photo (valid for a few minutes), or null
batchesonly with include=batches: up to 500 batches, sorted by expiry date
batches_truncatedonly 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​

FieldRequiredRules
nameyes1 to 255 characters
codenoup to 100 characters
days_to_be_nextnointeger from 0 to 3650
brand_id, category_idnomust exist in the organization
store_idnomust exist in the organization and be active
idnoUUID 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.