Rate limits

Usage is metered

Every call to the Admin, Partners and Front APIs is measured, per marketplace and per API. Traffic that harms a marketplace can be throttled or refused, and limits can change. Write your client so that it behaves well under any limit:

• treat 429 Too Many Requests as retryable, and honour a Retry-After header when the response has one;
• retry 502, 503 and 504 with exponential backoff and jitter;
• never retry a 4xx other than 429 without changing the request.

Follow your usage

Administrators can see the traffic of their marketplace in Settings → API usage (/admin/settings/api-usage): calls per API, latency, status codes, the busiest endpoints and the errors, over the last 1 to 90 days. Use it to check what an integration really does before and after you ship it.

Build a client that scales

Use webhooks instead of polling. To react to new orders or updated listings, subscribe to webhooks and keep polling for a periodic catch-up only. See Sync orders to an ERP.

Ask for less. List endpoints accept fields to return only the attributes you need and limit up to 100 per page. See Pagination and filtering.

Write sequentially for a given vendor. Parallel writes on the listings of the same vendor wait for each other and slow each other down. Send them one after the other, or spread parallel workers across different vendors.

Keep bulk requests reasonable. POST /api/v1/listings/bulk processes the listings of the batch one by one, inside a single request, and downloads every image URL while it does. A batch of a few dozen listings with images can take a long time to answer. Prefer batches small enough to complete well within your HTTP client’s timeout, and make your import resumable, as described in Import a catalog.

Cache what rarely changes. Categories, attributes, order types and user groups change when the marketplace owner reconfigures the marketplace, not on every request. Read them once per import or once per hour, not once per listing.