Pagination

All list endpoints (GET /rest/{domain}/{entity}) return paginated results.

Query Parameters

Parameter	Default	Description
page	1	Page number (1-based)
limit	15	Items per page (storefront requests are capped — see Maximum Page Size)

Example: GET /rest/product/product?page=2&limit=25

Maximum Page Size

For storefront callers (guest and customer — anything that is not a backend/admin token), limit is capped at a server-side ceiling of 1000. A request that asks for more is not rejected: it is silently clamped to the ceiling, the response still comes back 200 OK, and there is no error or extra field indicating that anything was reduced.

The ceiling exists to bound the cost of a single request — without it, an explicitly supplied limit is unbounded. A shop that wants a tighter bound than 1000 lowers rest_max_page_size for itself.

Always read the actual page size back from pagination.per_page rather than assuming the limit you sent was honoured — that's the only reliable way to detect a clamp and page through the rest of the result set (pagination.total_pages, pagination.has_next).

GET /rest/product/product?limit=47419   (storefront token)

"pagination": {
  "per_page": 1000,   // clamped — not 47419
  ...
}

Backend callers are exempt and may request any page size.

The ceiling is configurable per shop via the rest_max_page_size key in application/config/app.php (defaults to 1000; an absent, non-numeric, zero or negative value also falls back to 1000). It only bounds a limit that is explicitly supplied above the ceiling — the default of 15 when limit is omitted, empty, or 0 is unaffected.

Why this is not the same number as listing.perPageMax

GET /rest/storefront-config reports listing.perPageMax, typically 72. That is a different value with a different job, and the two are deliberately not equal:

	value	what it is	enforced?
listing.perPageMax (/rest/storefront-config)	72	the largest page size the shopper-facing selector should offer, so a headless storefront renders the same "show 9 / 18 / 36 / 72" control as the rendered storefront	no — advisory
rest_max_page_size (this ceiling)	1000	the largest page size the server will serve to a storefront caller	yes

So perPageMax answers "what should I put in my page-size dropdown?" and the ceiling answers "what is the most I can ask for at all?". The ceiling is deliberately the larger of the two, leaving headroom for legitimate non-selector reads — a facet computation or a data sync — that are not driven by the shopper's dropdown.

Use listing.perPageMax to build your selector. Do not use it to predict a clamp: a limit between 72 and 1000 is served in full, and only above 1000 is anything reduced. They come from separate config keys (products_list_max and rest_max_page_size) and a shop may change either independently.

Response Format

List responses include a pagination object alongside the data array:

{
  "success": true,
  "data": [
    { "id": 1, "name": "..." },
    { "id": 2, "name": "..." }
  ],
  "pagination": {
    "current_page": 2,
    "per_page": 25,
    "total": 142,
    "total_pages": 6,
    "has_next": true,
    "has_prev": true
  }
}

Single Entity Responses

GET /rest/{domain}/{entity}/{id} (show) and GET /rest/{domain}/{entity}/item (item) return a single object without pagination:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "..."
  }
}

The item endpoint accepts the same filters as index but returns only the first matching entity.