Rate Limits
Rate limits are applied to our API to ensure fair usage and prevent abuse. Different limits apply depending on the authentication method used and the plan selected by the user.
API KEY and Bearer Token Users
Rate limits for API KEY and bearer token users are determined by the sales plan chosen. The following limits apply:
- Free Plan: 10 calls per day.
- Standard Plan: 300 calls per day.
- Premium Plan: 15,000 calls per day.
- Business Plan: 50,000 calls per day.
- Enterprise Plan: Custom limits, agreed per contract.
The daily allowance is shared by the whole account: every user, every API key and every PromoSync store draw on the same count. Sub-accounts draw on their parent account’s allowance. The count resets at 00:00 UTC.
API Boosts
Need more calls on a busy day, for a catalog import, a price sync or a seasonal peak? API Boosts are prepaid packs of extra calls for the Standard, Premium and Business plans. You buy them from Account Settings in the dashboard and pay on Stripe’s secure checkout page. The calls usually start working within a couple of minutes of paying.
| Pack | Price | Per 1,000 calls |
|---|---|---|
| 5,000 calls | $39 | $7.80 |
| 25,000 calls | $99 | $3.96 |
| 100,000 calls | $249 | $2.49 |
How a Boost works:
- It is a pool of calls for your whole account. It is used only after the day’s plan allowance is gone; your daily limit itself does not change, and the next day starts with the plan allowance again.
- Packs are valid for 12 months from purchase. Unused calls expire; they are not refunded.
- You can hold up to two active packs at a time. The pack expiring first is used first.
- A Boost adds calls, not features. Your plan’s feature set and user limit stay the same.
- Free, Trial and Enterprise accounts cannot buy Boosts. Enterprise capacity is agreed per contract.
- Account Settings shows each pack with its remaining calls, purchase date and expiry date, and the combined balance.
When both the daily allowance and your packs are used up, calls get a 429 Too Many Requests response until 00:00 UTC, or until you add another pack.
Rate Limit Headers
Every response to a call that counts against your daily allowance carries three headers, so you can track your usage without a separate request:
| Header | Value |
|---|---|
X-RateLimit-Limit | Your account’s daily allowance. |
X-RateLimit-Remaining | Calls left today, after counting this one. |
X-RateLimit-Reset | When the allowance starts over: the next 00:00 UTC, as a Unix timestamp in seconds. |
HTTP/1.1 200 OK
X-RateLimit-Limit: 15000
X-RateLimit-Remaining: 13818
X-RateLimit-Reset: 1793923200What to expect from them:
X-RateLimit-Remainingis a close estimate. Calls are counted across several servers that sync every few seconds, so the number can trail your real usage by a few calls. Use it to pace your jobs; the429is what tells you the allowance is gone.- The
429carries them too, withX-RateLimit-Remaining: 0. - Accounts with no daily limit do not get these headers. There is no number to report.
- Calls that do not count against the allowance, such as
GET /me, do not carry them. - Sub-accounts see the parent account’s shared allowance, since that is the count that applies to them.
- API Boosts: once the plan allowance is used,
X-RateLimit-Remainingstays at0while a pack covers your calls. Your pack balance is in Account Settings. - Browser clients can read all three: they are exposed through CORS, along with
X-Request-ID.
Telling 429 Responses Apart
Two different situations answer 429 Too Many Requests, and they call for different handling:
| Daily allowance used | Supplier throttling | |
|---|---|---|
| What happened | Your account has used its calls for the day. | The supplier asked for fewer calls per minute. |
| Body | {"detail": "You have exceeded the rate limit: ..."} | {"code": "supplier_rate_limited", "retry_after": 60, "supplier_code": "...", "message": "..."} |
Retry-After header | Never sent | Sent when the supplier says how long to wait |
| What to do | Stop until X-RateLimit-Reset, or add an API Boost pack. Retrying sooner will not help. | Wait Retry-After seconds, then retry the same call. |
Important Notes
- Exceeding Rate Limits: If you exceed the rate limits, a
429 Too Many Requestsstatus code will be returned. You must wait until the rate limit window resets to make additional calls, or add an API Boost pack if your plan allows it. - Upgrading Plans: If your needs exceed the rate limits of your current plan most days, consider upgrading to a higher plan through your user dashboard. The change will take effect immediately. If you only need more calls now and then, an API Boost is usually the cheaper option.
- Burst Behavior: Please note that rate limits are enforced per day. Any unused calls do not roll over to the next day.
Considerations for Implementation
- Caching: Consider caching results locally to minimize the number of calls and stay within the rate limits.
- Monitoring: Read
X-RateLimit-Remainingon your responses to keep track of the calls you have left and prevent unexpected rate limit issues. - Handle 429s gracefully: When the daily allowance is used, pause and retry after 00:00 UTC (
X-RateLimit-Reset) instead of failing a whole job. If you run imports or price syncs, plan them around your daily allowance or buy a Boost before you start. - Selecting the Right Plan: Choose the plan that best fits your needs, taking into consideration the rate limits and the nature of your application.
By adhering to these rate limits, you contribute to a fair and stable environment for all users of our API.