Pagination

All list endpoints in the Mercel API return the same response envelope. To page forward, follow nextPageUrl; to page backward, follow previousPageUrl. The cursor and all filter parameters are baked into the URL, so clients never reconstruct queries between pages.

Response shape

Every list endpoint — paginated or not — returns:

{
  "data": [
    { "id": "prd_…", "name": "..." }
  ],
  "nextPageUrl": "https://api.mercel.app/v1/products?limit=20&page=eyJrIjpbIjIwMjYtMDUtMjJUMTI6MDA6MDAuMDAwWiIsInByZF8wMUhIOSJdLCJkIjoiZiJ9",
  "previousPageUrl": null
}

Field	Type	Description
`data`	array	The items on this page.
`nextPageUrl`	string \| null	URL to fetch the next page. `null` at end-of-list or for unpaginated resources.
`previousPageUrl`	string \| null	URL to fetch the previous page. `null` on the first page or for unpaginated resources.

Both URL fields include all filter params and the opaque cursor — clients pass them back unchanged.

Paging forward

# Initial request
curl https://api.mercel.app/v1/products?limit=20 \
  -H "Authorization: Bearer mercel_pat_…"

# Then follow nextPageUrl until it's null
curl "$NEXT_PAGE_URL" \
  -H "Authorization: Bearer mercel_pat_…"

When nextPageUrl is null, you've reached the end of the list.

Paging backward

The previousPageUrl field returns a URL that fetches the page immediately before the current one. Useful for "back" buttons in paged UIs.

curl "$PREVIOUS_PAGE_URL" \
  -H "Authorization: Bearer mercel_pat_…"

previousPageUrl is null on the first page.

Request parameters

Every list endpoint accepts these query parameters:

Parameter	Type	Description
`limit`	integer	Maximum number of items to return per page. Defaults to 20, capped at 100.
`page`	string	Opaque pagination token. Don't construct this yourself — pass the value returned in `nextPageUrl` or `previousPageUrl`. The encoding is internal and may change.

Some endpoints' result sets are small today (the organizations a user belongs to, the catalog of notification types, the user's registered push devices) and return every row in one response with both URL fields null. They still accept limit and page so the contract stays stable if the result set ever grows — the day an endpoint flips on real pagination, no parameter signature changes. SDK consumers can treat every list call identically.

Stability and ordering

Lists are returned in reverse chronological order by default (newest first).
Pagination is keyset-based — adding rows after a given cursor doesn't skew the page boundaries.
Filter params (unreadOnly, storeId, etc.) are baked into nextPageUrl / previousPageUrl. They can't drift mid-traversal.
An invalid page token returns 400 VALIDATION. If you receive one, you almost certainly built it yourself instead of following the URL.

Caveats

Resources may shift mid-traversal. If a row is inserted or deleted between page fetches, the cursor still points at a stable position in the underlying ordering — items inserted after your cursor will appear on the next page, items deleted before will be skipped. Treat list responses as a snapshot in time per page.
Don't cache nextPageUrl across long sessions. The opaque cursor format may change in future versions; URLs are only meant to be followed in the short window between fetches.