Etiquette for Using Order Desk’s API
Order Desk’s current API has no limitations on use. Users are free to use any time-frame of search and request information at any speed they desire. But just because you can, doesn’t mean you should.
In this guide, we’ll cover a few courtesies we would certainly appreciate you applying to allow us to continue the liberal use of our API.
Speed of Requests
We strongly encourage developers to use sensible and efficient request rates to ensure stable and consistent performance for all users. As a guideline, we recommend keeping API requests at or below 100 requests per minute per client (this is not currently enforced). This rate allows for responsive and reliable service while preventing overload on our systems, especially during periods of high demand.
Excessive or poorly managed request rates can lead to throttling, delayed responses, or even temporary suspension of access. To avoid this, implement rate-limiting logic in your application, such as request queuing, caching of frequent queries, and exponential back-off strategies when retrying failed requests. By being considerate of your request frequency, you help maintain a healthy ecosystem that benefits both your application and others using the service.
Also consider whether the frequency of which you’re making repeat queries for the same information, such as long-polling, is too frequent. We may even have ways to support not needing to long-poll our system depending on your use-case. You can always email us at tech@orderdesk.com to ask.
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. Thoughtful use of date ranges, combined with sensible request rates, is key to maintaining a stable and scalable integration.
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. Keeping your queries lean and purposeful is an essential part of responsible API usage.
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.