Skip to main content

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…"
}
}
ParameterDescription
limititems per page: default 50, maximum 100
cursorthe 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.
Why a cursor and not a page number

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:

  1. Save the current instant in UTC as start.
  2. Download each list in full (categories, brands, stores, products, batches), following the cursors.
  3. Save start as last_sync.

Next times:

  1. Save the current instant as start.
  2. For each list, fetch with updated_since=last_sync and follow the cursors. Create or update the received items in your system.
  3. Fetch /v1/deletions?since=last_sync, follow the cursors and delete the listed items.
  4. Save start as last_sync.

Tips:

  • Use a small safety margin, for example updated_since 2 minutes before the last sync. Repeated items are harmless: just update by id.
  • 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.