Rate limit

Learn about our API rate limits and how to work with them effectively.

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	Limit	Notes
Read all subscriptions	2 requests / 3s	Separate pool; does not reduce global 10 requests/s.
List Products	6 requests / s	Separate pool; does not reduce global 10 requests/s.
Read all orders	2 requests / 3s	Separate pool; does not reduce global 10 requests/s.
Read all scheduled orders	2 requests / 3s	Separate pool; does not reduce global 10 requests/s.
Read all customers	1 requests / s	Separate pool; does not reduce global 10 requests/s.
List activity logs	2 requests / 3s	Separate pool; does not reduce global 10 requests/s.
Read inventory actions	5 requests / s	Separate pool; does not reduce global 10 requests/s.

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

---

How enforcement works

1. Global pool (default endpoints): Fixed 1-second budget of 10 per store.

2. Per-endpoint pools (overrides): Each overridden endpoint has its own fixed window per store.

3. 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/sec for all non-overridden endpoints.
• One limiter per overridden endpoint: based on that endpoint’s rate/window.
  A request touches exactly one limiter: global or the endpoint’s own pool.

2. Reduce volume

Paginate and filter list endpoints, cache hot reads, and schedule polling with jittered intervals.

---

FAQs

Do overridden endpoints consume the global 10 rps?

-> No. Each overridden endpoint has an independent pool. The global pool is only for non-overridden endpoints.

If an overridden endpoint is 6 rps, what’s my max alongside other traffic?

-> Up to 6 rps for that endpoint plus up to 10 rps across non-overridden endpoints.

Are limits per store or per API key?

-> Per store. Multiple API keys/apps for the same store share these pools.

Can we request higher limits?

-> Contact Support with your store ID, endpoints, steady/peak rates, and burst patterns.