Backend API requests are rate limited per store, and separately for each environment. Limits apply to throughput — how many requests you can make over time — and to concurrency, or how many can be in flight at once. The exact figures depend on your plan; contact Swell if you need to know the limits that apply to your store.

How requests are counted

Requests aren't counted one for one. Each request has a weight based on how much work it asks the database to do, and it's the weight that counts against your limit. An ordinary request weighs 1, and the following add to it.

  • Each $lookup stage in an aggregate pipeline adds 1.
  • Every two expanded fields add 1, rounded down. A nested term such as parent.parent counts as two.
  • Each include adds 1, and an include with its own query adds that query's weight on top.
  • The first 3 points of combined expand and include weight are free, so modest queries cost the same as a plain request.

A batch weighs the sum of the operations inside it, and a transaction weighs one point per operation plus one. Grouping calls saves round trips, but it doesn't buy you extra quota.

What happens at the limit

Going over the limit doesn't fail immediately. Requests beyond your throughput are queued and run as capacity frees up, so a short burst simply takes longer to clear. A request that waits more than 60 seconds is dropped and returns 429 Too many requests, which means a 429 signals sustained pressure rather than a single spike. Back off and retry rather than retrying immediately.

Light read traffic is metered separately so that storefront requests aren't held up behind heavy back-office queries. Inexpensive GET requests to products, variants, categories, attributes, accounts, carts, purchase links, and content pages and blogs — along with cart updates — draw on their own pool.

Test environments

Test environments always use the lower tier, whatever your plan allows in production. Load testing against a test environment measures the test tier, not what your live store can do.

Staying under the limit

  • Ask for what you need. Trimming unnecessary expands and includes lowers the weight of every request you make.
  • Prefer one aggregate over many small queries when you're summarizing data, and page through large result sets rather than requesting them repeatedly.
  • Treat 429 as backpressure: retry with increasing delays, and spread bulk work such as imports over time instead of firing it all at once.