Pagination, limits & versioning

Cross-cutting rules that apply across all endpoints.

Pagination & filtering

List endpoints are paginated and return counters inside data:

{
  "data": {
    "product": [],
    "count": 420,
    "offset": 0,
    "limit": 20
  }
}

• Page through with offset + limit, or page + limit, depending on the endpoint — keep requesting until offset + len(items) >= count.
• Filters are query params. Many accept comma-separated values (id=1,2,3, clientId=A,B). Common ones: organizationId (required), storeId, status, and your clientId.

Paging keys are not uniform across services. Most services use page/limit (or offset/limit); a few use perPage instead of limit, and a couple return offSet. Follow the exact params shown on each reference page rather than assuming.

Rate limits

Treat every endpoint as rate-limited and implement backoff. The storefront gateway enforces per-method limits by default:

Some high-traffic or sensitive routes have tighter per-endpoint overrides. When you exceed a limit you get 429 — back off exponentially and retry. Limits are per deployment and may change, so don't hard-code them.

Versioning

The API is versioned with the X-API-VERSION request header. Omit it for the default (v1); send v2 to opt into a v2 endpoint where one exists:

GET /api/catalogue-service/product?organizationId=<org-id> HTTP/1.1
Authorization: Bearer <token>
X-API-VERSION: v2

Versions are additive — v1 keeps working when v2 ships. Pin the version you tested against and upgrade deliberately.

Idempotency

There's no idempotency-key header today. Make writes safe to retry by:

• setting your own clientId on creates, so a retried create updates the existing record instead of duplicating it;
• matching payments/refunds on transactionId / gatewayTransactionId.

See Responses & errors → Retrying safely.

Other headers worth knowing

• Accept-Language — with MultiLingualSupport, returns localized catalog fields.
• storeId (as a param) — scopes price, stock, slots and orders to a store.