Rate limiting and throttling

The unit of rate limiting

Rate limiting is applied per app × store combination. Even for the same app, a different store is a separate count.

Per-plan limits (store-side plan)

Short bursts are allowed up to 2x via a token-bucket scheme.

Response headers

Every API response includes the current rate-limit status.

X-RateLimit-Limit: 10           ← per-second upper limit
X-RateLimit-Remaining: 7        ← remaining
X-RateLimit-Reset: 1745740001   ← reset time (Unix seconds)
X-RateLimit-Resource: receipts  ← the target of the limit

When you hit the limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Remaining: 0

{ "error": { "code": "rate_limited", "message": "..." } }

Implementation to avoid hitting the limit

1. Client-side throttling

Have a mechanism to limit the send rate on the client side as well. Rather than waiting for a 429, controlling throughput from the start is more stable.

// A simple token-bucket example
class RateLimiter {
  constructor(perSecond) {
    this.tokens = perSecond;
    this.max = perSecond;
    setInterval(() => { this.tokens = this.max; }, 1000);
  }
  async acquire() {
    while (this.tokens <= 0) await sleep(50);
    this.tokens--;
  }
}

2. Use batch endpoints

ReceiptRoller provides batch APIs that handle multiple resources in one request. They are more favorable for rate limits than calling one at a time.

POST /v1/products/batch
{
  "products": [
    { "sku": "A001", "name": "..." },
    { "sku": "A002", "name": "..." }
  ]
}

3. Caching and delta retrieval

• Cache data that rarely changes (store information, product master) on the client side
• For list retrieval, fetch only the delta with updated_after
• Receive notifications via Webhook and then fetch details via the API (drop polling entirely)

4. Controlling concurrency

Keep the number of concurrent requests at or below the per-second limit. Firing all of them concurrently with Promise.all results in a 429 in no time. Control the number of concurrent executions with something like p-limit.

Consulting about relaxing the limit

If your workload characteristics unavoidably exceed the limit, it can be relaxed via an individual contract on the Enterprise plan. Consult the sales desk or support.

Related guides

• Error codes and retry guidance
• The basics of requests and responses
• Back to the developer help index