Partners API

Rate Limiting

A leaky bucket per store: 50 requests of burst, refilling at 2 per second.

How it works

We rate limit requests following a leaky-bucket strategy. Your bucket holds a burst of 50 requests, and it drains — recovering capacity — at 2 requests per second.

In practice that means you can fire up to 50 requests instantly, then sustain a steady 2 requests per second forever. Go beyond the burst and the API responds with:

HTTP/1.1 429 Too Many Requests

The bucket keeps draining while you back off, so a short pause is always enough to get going again.

Handling 429s

• Retry with exponential backoff and jitter. A 429 is not an error in your integration — it is the API asking you to slow down.
• Smooth your bursts. If you sync in batches, queue requests at ~2 per second instead of firing them all at once.
• Fetch more per request. List endpoints accept items=250 — ten times the default page size. See Pagination.
• Prefer webhooks to polling. Webhooks push changes to you as they happen. See Webhooks.

const withBackoff = async (request, attempts = 5) => {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await request();
    if (response.status !== 429) return response;

    const delay = 500 * 2 ** attempt + Math.random() * 250;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Rate limited after retries");
};