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.
Rate limits
Section titled “Rate limits”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.
Handle a 429
Section titled “Handle a 429”- Stop sending requests of that kind.
- 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-strictorRetry-After-auth-standard, and the value is a number of seconds. The plain nameRetry-Afteris not sent. Browser code on another origin cannot read these headers. - Wait that long, or if there is no header, wait a few seconds and double the wait after each further 429.
- 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")}Paginate a list
Section titled “Paginate a list”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.
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.
Filter by date
Section titled “Filter by date”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.
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.