Rate limits

Overview

We use two pool rate limit system:

1. Global pool

Limit: 10 requests per second per store
Applies to: All endpoints that don't have a specific override
Purpose: Ensures overall API stability

2. Endpoint-Specific Rate Limits

Purpose: Provides dedicated capacity for certain operations
Independence: These limits operate separately from the global limit
Benefit: Allows you to make calls to these endpoints without affecting your global limit quota

When a limit is exceeded, the API returns HTTP 429 (Too Many Requests) with retry guidance.

Treat limits as ceilings, not targets. Keep steady usage below the limits and add jitter to avoid burst collisions.

Endpoint-specific overrides (per store, isolated from the global pool)

Endpoints not listed here draw from the global 10 requests per seconds per store pool.

Endpoint	Requests	Time window	Notes
Read all subscriptions	2 req	3 seconds	Separate pool; does not reduce global 10 requests/s.
List Products	6 req	1 second	Separate pool; does not reduce global 10 requests/s.
Read all orders	2 req	3 seconds	Separate pool; does not reduce global 10 requests/s.
Read all scheduled orders	2 req	3 seconds	Separate pool; does not reduce global 10 requests/s.
Read all customers	1 req	1 second	Separate pool; does not reduce global 10 requests/s.
List activity logs	2 req	3 seconds	Separate pool; does not reduce global 10 requests/s.
Read inventory actions	5 req	1 second	Separate pool; does not reduce global 10 requests/s.

Note: “2 requests per 3 seconds” allows a small burst of 2, replenished over a fixed 3-second window—completely independent of the global pool.

How enforcement works

Global pool (default endpoints): Fixed 1-second budget of 10 per store.
Per-endpoint pools (overrides): Each overridden endpoint has its own fixed window per store.
Admission rule:
- For non-overridden endpoints → check global 10 rps only.
- For an overridden endpoint → check that endpoint’s pool only.

Concrete examples

Separate pools in action
- t=0s: You make 5 calls to Read Inventory Actions (5 rps pool) and 10 calls across non-overridden endpoints (global pool).
- Result: All 15 requests can succeed (subject to each pool’s own limits).
Hitting an endpoint cap doesn’t affect the global pool
- t=0s: You send 6 Read Inventory Actions calls.
- Outcome: 5 admitted; 1 returns 429 with endpoint-override.
- You still have the full 10 rps available in the global pool that second.
3-second window overlap
- t=0s: Send 2 List Subscriptions calls (2/3s cap) and 10 calls to non-overridden endpoints.
- Result: All 12 admitted; additional List Subscriptions calls before t<3s will 429 due to its own pool, but you can still use the global pool each second.

Client guidance

1. Implement separate limiters

Global limiter: 10 requests per second for all non-overridden endpoints.
One limiter per overridden endpoint: based on that endpoint’s rate per window.
A request touches exactly one limiter: global or the endpoint’s own pool.

2. Optimize your calls

Use pagination and filters to reduce the size of list requests.
Cache frequently accessed data.
Schedule polling with randomized jitter to distribute load..

FAQs

Do overridden endpoints consume the global 10 rps?

-> No. No. Each endpoint with a specific limit has an independent pool. The global pool is only for endpoints not listed in the specific limits table.

If an endpoint has a 6 rps limit, what is my maximum throughput?

-> You can make up to 6 requests per second to that specific endpoint, plus up to 10 requests per second to any other endpoints that fall under the global limit.

Are limits per store or per API key?

-> Limits are per store. All API keys and applications for the same store share the same rate limit pools.

Can we request higher limits?

-> Yes. Please contact Support with your store ID, the endpoints in question, and details about your steady/peak traffic patterns.