Pagination

All list endpoints use cursor-based pagination for consistent, performant results.

Request Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Items per page (1–100)
`starting_after`	string	—	Cursor: return items after this ID

Response Format

{
  "data": [
    { "id": "prod_abc", "name": "Product A" },
    { "id": "prod_def", "name": "Product B" }
  ],
  "has_more": true,
  "next_cursor": "prod_def"
}

Field	Type	Description
`data`	array	The list of items
`has_more`	boolean	Whether more items exist after this page
`next_cursor`	string \| null	The ID to pass as `starting_after` for the next page

Example: Fetching All Products

let cursor: string | undefined;
const allProducts = [];

do {
  const params = new URLSearchParams({ limit: '100' });
  if (cursor) params.set('starting_after', cursor);

  const res = await fetch(
    `https://api.headlesscommerce.io/v1/storefront/products?${params}`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );
  const body = await res.json();

  allProducts.push(...body.data);
  cursor = body.has_more ? body.next_cursor : undefined;
} while (cursor);

Filtering & Sorting

List endpoints also support query parameters for filtering and sorting:

# Filter by status + sort by creation date
GET /v1/admin/products?status=active&sort=created_at&order=desc&limit=50

Common filter parameters vary by resource — refer to each endpoint’s documentation for details.