Rate limits
Bound concurrency and retry safely without assuming undocumented request quotas.
The merchant API does not currently publish a guaranteed requests-per-second quota, burst allowance, or RateLimit headers. Do not hardcode a throughput budget from examples or assume unlimited capacity.
Client behavior#
Keep concurrency bounded, queue work, and prefer webhooks plus targeted GET requests over continuous polling of entire lists. Retry transient failures with exponential backoff and jitter; use the same idempotency key and request body for writes.
Honor Retry-After when present on a retryable response. It can express a delay in seconds or an HTTP date. If it is absent, use your own bounded backoff policy.
Request and collection limits#
| Limit | Value |
|---|---|
| JSON request body | 1 MiB |
List page limit | Default 20, at most 100 items |
List cursor | At most 8192 characters |
| Webhook endpoints | At most 16 per merchant/environment |
These are request-size and collection limits, not throughput commitments.
Handle overload#
A 503 can mean temporary service unavailability or an unresolved outcome. A 429, if received, means the request must wait. Neither response authorizes a new idempotency key for a mutation whose outcome is unknown.
See errors, pagination, and idempotency for the retry and synchronization rules.