Skip to content

Public API: pagination, sync and idempotency

How to walk long lists with the cursor, fetch only what changed and repeat a POST without creating duplicates.

Cursor pagination

Lists return { "data": [...], "nextCursor": "..." }. For the next page, repeat the request with cursor= and the value of nextCursor. When nextCursor is null there is nothing more. Choose the size with limit (1 to 200, default 50). Results are sorted by change date (updatedAt) and then by id, so a page neither skips nor repeats records even if new data arrives while you walk the list.

Fetch only what changed

Store the updatedAt of the last record you processed and, on the next sync, ask for updatedSince= with that date (ISO 8601 format, for example 2026-11-14T08:00:00Z). For stock, updatedSince also returns the products whose warehouse stock changed.

Idempotency-Key on POST

Creating a customer or an order requires the Idempotency-Key header with a value you choose (1 to 120 characters: letters, digits, -, _, ., :), for example the order number in your website.

  • If you repeat the request with the same key and the same body (after a network cut), you get the first response with the header Idempotent-Replayed: true. Nothing new is created.
  • The same key with another body gives 409 API_IDEMPOTENCY_KEY_REUSED: use a new key for a new operation.
  • If the first request is still being processed you get 409 API_IDEMPOTENCY_IN_PROGRESS: wait and repeat it.
  • If the operation failed (for example, a product that does not exist), you can fix it and repeat with the same key.
  • Keys are kept for 24 hours.
Back to the help centre