This guide covers a few courtesies we appreciate you following so we can continue providing reliable access to our API.
Rate Limits
To keep performance stable for everyone, our API enforces rate limits. This prevents any single user from overwhelming the system and helps maintain fair access. Please build your code with these limits in mind.
We use a leaky bucket algorithm with the following limits:
- Initial bucket size: 20 requests
- Refill rate: 3 requests per second
- This gives you about 100 requests over a rolling 30 second window.
Each request consumes one token. To stay within the limits, check the X-Tokens-Remaining header in the API response.
If you exceed the limit, you’ll receive an HTTP 429 Too Many Requests error. When this happens, check the X-Retry-After header to see how many seconds to wait before sending more requests. Pausing for that duration will prevent further errors.
You can learn more in our API reference docs.
Add a Date Range
To improve performance and reduce unnecessary load, include a date range in your order based API queries whenever possible. Setting a clear start and end date limits the amount of data returned and keeps responses faster and more efficient.
Avoid large open ended queries unless absolutely necessary. For example, instead of requesting “all orders,” request “orders from the past 7 days” or “orders from the past 6 months.” This helps your application handle data more predictably and reduces strain on the system.
Review Your Queries
Regularly review your scheduled or automated API queries to make sure they are still needed. Over time, systems often accumulate outdated or redundant requests, such as duplicate pulls or legacy integrations that are no longer in use.
Auditing these queries helps reduce unnecessary API usage and supports overall system performance and reliability.
Add a Unique User-Agent
We strongly recommend including a unique User-Agent header in your API requests. This should identify your application and include your store ID, for example:
User-Agent: StoreName/Store-ID (your-url.com)Using a custom User-Agent helps us diagnose issues, monitor usage, and contact you if we detect something that may affect your integration. Please keep it consistent and up to date.
Ask Us If You’re Unsure
If you’re building workarounds or making complex requests because something does not quite fit your needs, reach out to us. We’re happy to review your setup and suggest a more efficient option.
You can contact us anytime at tech@orderdesk.com. Conversations like this help us improve the API for everyone.