Skip to main content

Response headers and paging limits in the reference

2026-11-18 · Not breaking · Upcoming: not yet in production

The reference now declares the response headers Location and Idempotent-Replayed and the default and largest page size of every list, as the API already sends and applies them.

What changed

  • Location is declared on the 201 of POST /api/v1/orders, POST /api/v1/orders/{id}/lines, POST /api/v1/orders/{id}/shipments, POST /api/v1/orders/{id}/shipments/{shipmentId}/void, POST /api/v1/fulfillment/nodes and POST /api/v1/webhooks, and on the 409 order-already-exists of POST /api/v1/orders.
  • Idempotent-Replayed: true is declared on the 201 of POST /api/v1/orders, POST /api/v1/orders/{id}/shipments, POST /api/v1/orders/{id}/shipments/{shipmentId}/void, POST /api/v1/orders/{id}/lines/{lineId}/cancellations, POST /api/v1/orders/{id}/lines/{lineId}/returns, POST /api/v1/orders/{id}/payment-facts, POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events and POST /api/v1/fulfillment/nodes. It is sent only when a request with the same Idempotency-Key and body is answered again, never on the 200 for a fact that was already reported.
  • offset and limit of GET /api/v1/fulfillment/nodes, GET /api/v1/orders/{id}/shipments and GET /api/v1/orders/{id}/parcels/{parcelId}/tracking-events declare their default and maximum; a limit above the maximum gives 400, as before.
  • pageSize of GET /api/v1/orders and GET /api/v1/orders/{id}/timeline and limit of GET /api/v1/orders/stats/top-articles declare their default and maximum, and their descriptions say that a larger value is clamped to the maximum, as before.
  • page and pageSize of GET /api/v1/orders/{orderId}/webhook-deliveries and GET /api/v1/webhooks/{webhookId}/deliveries declare their default.
  • The webhook operations describe the signature, the headers, the retries and the payload of a delivery, as the webhooks guide does.
  • Nothing you send or read changes.

Affected operations

  • Every operation named under What changed, in the reference only.

What you do

  • Nothing. A client generated from the reference can now read Location and Idempotent-Replayed and knows the page sizes.