Skip to content

Rate limits and pagination

This guide covers two things you meet once you build a real integration. First, what the API limits and what to do when it says slow down. Second, how to read a long list one page at a time.

There is no per-key rate limit today. A secret key that calls the Store API is not counted per minute or per day, and the API does not send rate limit headers on those calls, except on the routes in the table below (purchase order send and PDF, test email send). Those send X-RateLimit-Limit-<name> and X-RateLimit-Remaining-<name> on every response and Retry-After-<name> on a 429. Do not read this as a promise of unlimited speed. EcomWeb can add limits later, and a client that loops as fast as it can will load the store’s data and the shared service. Keep your own pace, for example a few parallel requests at most, and handle a 429.

The API limits these things today:

What Limit Counted by
Storefront customer sign-in routes that check a password or send an email: register, login, resend-verification, forgot-password, otp/request and anonymous 5 requests per minute Store and client IP address
The other Storefront customer sign-in routes: refresh, verify-email, reset-password, change-email/confirm, otp/verify, google/url, google/exchange and config 20 requests per minute Store and client IP address
Purchase order send and PDF download in the Store API 20 requests per minute Client IP address
Test email send for store email templates in the Store API 20 requests per hour Client IP address

The sign-in limits are counted per store, so a burst against one store does not block the shoppers of another.

When you hit a sign-in limit, the API answers 429 with the code AUTH_RATE_LIMITED:

{
"code": "AUTH_RATE_LIMITED",
"message": "Too many requests. Please try again in a moment.",
"timestamp": "2026-11-17T09:30:00.000Z"
}

Routes with other limits answer 429 as well, and their body can be the plain shape described in the errors guide.

  1. Stop sending requests of that kind.
  2. Read the wait from the response headers if your client can see them. The API names the header after the limit that was hit, for example Retry-After-auth-strict or Retry-After-auth-standard, and the value is a number of seconds. The plain name Retry-After is not sent. Browser code on another origin cannot read these headers.
  3. Wait that long, or if there is no header, wait a few seconds and double the wait after each further 429.
  4. Retry the request. Give up after a few tries and show the shopper or operator the message.
async function withBackoff(send: () => Promise<Response>, tries = 5) {
let wait = 2000
for (let attempt = 1; attempt <= tries; attempt++) {
const res = await send()
if (res.status !== 429) return res
const header = [...res.headers.entries()].find(([name]) => name.startsWith("retry-after"))
const seconds = header ? Number(header[1]) : NaN
await new Promise((r) => setTimeout(r, Number.isFinite(seconds) ? seconds * 1000 : wait))
wait *= 2
}
throw new Error("Still rate limited after retries")
}

List routes take these query parameters:

Parameter Meaning Default
limit Items per page, 1 to 10000 20
offset How many items to skip 0
sort_by The field to sort by. The allowed fields depend on the list, for example created_at or name for products Depends on the list
sort_order asc or desc Depends on the list, desc for products

Lists are paged by offset, not by a cursor. The response has the items in data and the paging state in meta:

{
"data": [{ "id": 101, "name": "Linen shirt" }],
"meta": {
"total": 134,
"limit": 20,
"offset": 0,
"page": 1,
"totalPages": 7,
"hasNext": true,
"hasPrev": false
}
}

page and totalPages are worked out from offset and limit. To read page 3, send offset=40 with limit=20.

Terminal window
curl "https://apibase.ecomweb.app/api/v1/stores/<store ref>/products?limit=50&offset=100&sort_by=created_at&sort_order=desc" \
-H "x-api-key: <secret key>"

To read every item, keep asking until hasNext is false:

const base = "https://apibase.ecomweb.app/api/v1"
async function* listProducts(storeRef: string, apiKey: string) {
const limit = 100
let offset = 0
while (true) {
const url = `${base}/stores/${storeRef}/products?limit=${limit}&offset=${offset}`
const res = await fetch(url, { headers: { "x-api-key": apiKey } })
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const { data, meta } = await res.json()
yield* data
if (!meta.hasNext) return
offset += limit
}
}
for await (const product of listProducts("<store ref>", process.env.ECOMWEB_API_KEY!)) {
console.log(product.id)
}

If items are added or removed while you read, an offset can skip or repeat an item. For a one-time export, sort by created_at ascending, so new items land at the end, and compare the number you read with meta.total when you finish.

Some lists filter by creation or update time with ISO 8601 timestamps:

Parameter Keeps items
created_after Created after this time
created_before Created before this time
updated_after Updated after this time
updated_before Updated before this time

The orders list supports all four. The payments list and the admin product reviews list also take them. The products list does not. Check the operation in the API reference before you rely on a filter, because an unsupported parameter is ignored.

Terminal window
curl "https://apibase.ecomweb.app/api/v1/stores/<store ref>/orders?updated_after=2026-11-01T00:00:00.000Z&limit=100" \
-H "x-api-key: <secret key>"

To sync changes, store the time you started the last run and pass it as updated_after the next time.