Etiquette for Using Order Desk’s API
In this guide, we’ll cover a few courtesies we would certainly appreciate you applying to allow us to continue the use of our API.
Rate Limits
To ensure stable and consistent performance for all users, our API enforces rate limiting. This prevents any single user from overwhelming the system and helps maintain fair access. Please build your code with these limits in mind.
Here’s how it works using a leaky bucket algorithm:
- Initial Bucket Size: 20 requests
- Refill Rate: 3 requests per second
- This gives you about 100 requests available over a rolling 30-second window.
Each request you make consumes one token from the bucket. To stay within the limits, you should check the X-Tokens-Remaining header in our API responses.
If you exceed the limit, you will receive an HTTP/1.1 429 Too Many Requests error. When this happens, check the X-Retry-After header. This will tell you the number of seconds you need to wait before sending more requests. Pausing your requests for that duration will prevent further issues.
You can learn more about this in our API reference docs.
Adding a Date
To improve performance and reduce unnecessary load, we recommend including a date range in your order-based API queries whenever applicable. Specifying a clear start and end date helps limit the volume of data returned, making responses faster and more efficient for both your application and our infrastructure.
Avoid requesting large, open-ended datasets unless absolutely necessary. For example, instead of querying for "all orders," request "orders from the past 7 days" or "orders from the past 6 months." This practice not only reduces response times but also ensures your application handles data more predictably.
Review Your Queries
We also encourage all users to regularly review their scheduled or automated API queries to ensure they remain necessary and efficient. Over time, it's common for systems to accumulate outdated or redundant requests, such as queries that no longer serve a business need, duplicate data pulls, or legacy integrations left running in the background.
By periodically auditing your scheduled queries, you can identify and remove those that are no longer useful. This not only reduces your API usage and potential costs but also contributes to overall system performance and reliability.
Adding a Unique User-Agent
To help us support and monitor usage more effectively, we strongly recommend that you include a unique User-Agent header in your API requests. This should identify your application or service and ideally include your store ID, for example:
User-Agent: StoreName/Store-ID (your-url.com)
Including a custom User-Agent allows us to better diagnose issues, track usage patterns, and notify you proactively if we detect any problems or changes that may affect your integration. It also helps distinguish your traffic from other clients, especially when troubleshooting or analyzing logs. Please ensure the User-Agent remains consistent and up to date with your deployments.
Ask Us if You Are Unsure
If you find yourself implementing a workaround or making excessive or complex requests because the API doesn’t quite meet your specific needs, please don’t hesitate to reach out. We welcome feedback and are happy to discuss ways to better support your use case.
In many cases, we can suggest a more efficient approach, or consider enhancements to the API that would simplify your integration. You can contact us anytime at tech@orderdesk.com, and we’ll be glad to assist. Collaboration like this helps us improve the API for everyone.