Rate limits

Each client IP is allowed 1,000 requests per rolling 24-hour window. Every response includes headers telling you how much of that budget is left.

#The window

• Limit: 1,000 requests
• Window: 24 hours, rolling
• Scope: per IP

The window slides — there is no fixed midnight reset. If you fire 1,000 requests in the first hour, you have to wait until those start rolling out 24 hours later before more capacity opens up.

#Response headers

Every response includes the standard draft-7 RateLimit-* headers:

RateLimit-Limit:     1000
RateLimit-Remaining: 873
RateLimit-Reset:     76234

RateLimit-Reset is the number of seconds until your oldest tracked request rolls out of the window.

The same information is also returned in legacy headers for older clients:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset:     1715212800

If you're writing a new client, read the standard RateLimit-* headers. The legacy X-RateLimit-* set is provided for compatibility.

#When you hit the ceiling

Once you exceed 1,000 requests in a 24-hour window, every request returns 429 Too Many Requests until enough requests roll out of the window to free capacity. The RateLimit-Reset header on the 429 tells you how long until that happens.

curl -i -X GET 'https://api.merch.com/v1/orders/list' \
  -H 'Authorization: Bearer <your_api_key>'

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 41892

#Best practices

• Batch when you can. Listing 100 orders in a single paged request is one call against the budget; polling for one at a time isn't.
• Cache. If your app reads the campaign list or the warehouse list on every order create, cache them. Those don't change often.
• Subscribe instead of poll. If you want to know when an order ships, subscribe to the order.shipped webhook rather than polling GET /v1/orders/{orderId} on a timer. See Webhooks reference.
• Back off on 429. Wait at least RateLimit-Reset seconds before the next request, or use exponential backoff with jitter so a fleet of clients doesn't all retry at the same instant.
• Watch RateLimit-Remaining. If you're approaching zero with hours left in the window, slow down before you hit 429.

#What doesn't count against the limit

Webhook deliveries are sent from Merch to your endpoint and do not consume any of your request budget. Only outbound calls from your client to api.merch.com count.