Reports

Using the reports endpoints in the REST API, you can generate and retrieve summary reports about your inventory and sales data.

Generating Reports

Reports take significant time to generate, so when you want a particular report, you first have to request that it be added to the report generation queue. You can do this with POST requests to the various report type endpoints. For example, if you want to get a report about your recent sales, you can send a POST request to the /reports/sales endpoint. This will queue the report for creation and it will generated asynchronously. You can check on the current status of your queued reports by sending a GET request to the /reports endpoint. All of your available reports will be returned, and those with a status of done have been generated and are ready for downloading.

Duplicate Report Requests

Only one report of a given type with the same parameters (e.g. the same storefront, date range, etc) can be pending at a time. If you request a report while an identical one is still queued or being generated, the request is rejected with status 403 and the problem type /problems/reports/already-pending:

{
  "type": "/problems/reports/already-pending",
  "message": "Access Forbidden",
  "errors": [
    {
      "field": "",
      "message": "A report with the same parameters is already pending (id_report: 1234)"
    }
  ]
}

Do not request the report again. Instead, poll the pending report via /reports/{id_report} and download it once its status is done. Use the type field, not the message, to detect this case.

This currently applies to /reports/account-listing only. Other report types will follow.

Downloading Reports

Once a report has finished being generated, it is available for download. When you query the /reports endpoint, one of the properties of a report is the id_report. You can use this property to retrieve the full meta-data for a single report from the /reports/{id_report} endpoint. You can download the report itself by requesting the file in the url property of the response, as long as the report is in the done state. Detailed descriptions of all of the reports endpoints are available on the endpoints documentation page.