question

When building an app that needs to backfill a merchant’s orders data, developers should make sure they follow the appropriate guidelines to ensure their app responsibly consumes the Clover REST API. Otherwise, they may experience interrupted service, resulting in a poor merchant experience. This answer will explain how to get orders, but the same instructions can be modified for payments.

Recent Orders (within the previous two months)

If you are querying for order data that is less than two months old, you can use the REST API orders endpoint. Note: each request is limited to 1000 orders per call, so you may need to make multiple requests using the offset query parameters.

https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders?modifiedTime>1497032132000&limit=1000
https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders?modifiedTime>1497032132000&offset=1000&limit=1000
https://apisandbox.dev.clover.com/v3/merchants/{mId}/orders?modifiedTime>1497032132000&offset=2000&limit=1000
...

The query parameters used are:

• modifiedTime - Limit to only orders created or modified less than 2 months ago. Time is defined in Epoch time (milliseconds). You can calculate this by subtracting the two months in milliseconds from the current Epoch time.
• offset - Paginate through large sets of results
• limit - Increase the number of results from the default of 100 to up to the max of 1000

All Orders (older than two months)

To request a list of orders greater than the last two months, developers must use the Export API. This API allows for bulk export of order and payment data. It reduces the likelihood of your app reaching our API rate limits. Each Export API request has a max time range of 30 days, so you may need to make multiple requests. 1000 objects per file are returned. If your response is more than 1000 objects it will return an array of files to capture. The Export API is only available during non-peak hours of:

• US: MON-FRI 08:00-12:00, SAT 09:00-12:00, SUN 09:00-13:00 (UTC)
• EU: MON-FRI 01:00-05:00, SAT 02:00-05:00, SUN 02:00-06:00 (UTC)
• Sandbox: No time restrictions

Since these times are outside of normal business, you may need to schedule a service to later run when the Export API is available. Additional details on how to use the API can be found in our GitHub.

If you have specific questions about your implementation or use case, please ask on Community or reach out to us privately. Pulling large amounts of data from many merchants runs the risk of severely interrupted service.