Pagination and sync
Cursor pagination
Every list is cursor-paginated and sorted by last change date (updated_at), oldest first.
{
"data": [ … ],
"pagination": {
"limit": 50,
"has_more": true,
"next_cursor": "eyJ1IjoiMjAyNi0xMS0wNlQx…"
}
}
| Parameter | Description |
|---|---|
limit | items per page: default 50, maximum 100 |
cursor | the next_cursor of the previous page |
To go through the whole list, repeat the call with cursor=next_cursor while has_more is true.
curl "https://api.validades.com/v1/products?limit=100&cursor=eyJ1IjoiMjAyNi0xMS0wNlQx…" \
-H "Authorization: Bearer vld_live_YOUR_KEY"
Cursor rules:
- it is an opaque string: do not build or change it;
- it only works for the same list and filters (a products cursor does not work on batches);
- items changed at the same instant are neither skipped nor repeated across pages.
Data changes all the time, from the team's devices and from the API itself. With page numbers, an item changed while you read moves position and can be skipped or repeated. The cursor avoids that.
Fetching only what changed: updated_since
Lists accept updated_since, an ISO 8601 instant with a time zone. The response only has items created or changed since that instant.
curl "https://api.validades.com/v1/batches?updated_since=2026-11-06T13:00:00Z&limit=100" \
-H "Authorization: Bearer vld_live_YOUR_KEY"
Deletions: GET /v1/deletions
Deleted items no longer appear in the lists, so updated_since does not show deletions. That is what the /v1/deletions route is for: it lists what was deleted in the last 90 days, including:
- deletions made in the app, on the website or through the API;
- cascade deletions (batches of a deleted product, products and batches of a store deleted with
cascade=true).
Incremental sync recipe
First time:
- Save the current instant in UTC as
start. - Download each list in full (categories, brands, stores, products, batches), following the cursors.
- Save
startaslast_sync.
Next times:
- Save the current instant as
start. - For each list, fetch with
updated_since=last_syncand follow the cursors. Create or update the received items in your system. - Fetch
/v1/deletions?since=last_sync, follow the cursors and delete the listed items. - Save
startaslast_sync.
Tips:
- Use a small safety margin, for example
updated_since2 minutes before the last sync. Repeated items are harmless: just update byid. - Sync categories, brands and stores first, then products and finally batches, so references already exist in your system.
- If your system goes more than 90 days without syncing, run a full sync again, because older deletions will no longer be available.
List filters
The filters of each list are on the reference pages. Unknown or invalid parameters are refused with 422 (validation_error), with the problem in details.