Export

Every list endpoint exposes an asynchronous export. The export runs as a background job and produces a downloadable file. Use it for large result sets instead of paging through the list endpoint.

Three actions are available on each list endpoint:

Action	Path	Purpose
Field discovery	{endpoint}/export_info/	Returns the exportable fields and supported file formats.
Start export	{endpoint}/export/	Starts a background job and returns a cache_key.
Check status	{endpoint}/export_status/	Returns the job status and the download URL.

Replace {endpoint} with the same path segment the list endpoint uses, for example baskets/baskets or orders/order-items. Each endpoint section shows this segment in its own path. Every list endpoint in this documentation offers all three actions, so any path you find here can be exported.

Step 1. Discover the Exportable Fields

GET {endpoint}/export_info/

{
    "fields": ["id", "status", "user_id", "user__email", "created_date"],
    "default_fields": ["id", "status", "user_id", "user__email", "created_date"],
    "available_export_formats": ["xls"],
    "default_export_format": "xls"
}

• fields lists every field you may request.

• default_fields lists the fields used when you request none.

Note: The exportable fields are not always the same as the fields the list endpoint returns. An export can expose related values, such as a user email address, that the list response reports only as a numeric ID. Call export_info before you build an export request.

Step 2. Start the Export

GET {endpoint}/export/?fields=id&fields=user__email&status=active

Supported parameters:

• fields: A field to include. Repeat the parameter for each field. The API ignores any value that export_info does not list, and falls back to default_fields when no valid field remains.

• limit: The maximum number of records to export. Omit it to export every matching record. The 1000-record page-size cap applies to list responses only and does not restrict an export.

• export_format: The output format. xls is currently the only supported value, and it is also the default. Any other value returns 400 Bad Request.

• Any filter the list endpoint supports. The export applies the same filters.

The response returns the key you poll with:

{
    "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11",
    "is_ready": false,
    "url": null,
    "error_message": null
}

An unsupported export_format returns 400 Bad Request:

{
    "error_message": "Unsupported file format. Supported formats: xls."
}

Note: The error_message text is translated into the language the instance is configured for, so its wording varies between environments. Branch on the status code, not on the message string.

Step 3. Poll for the Result

GET {endpoint}/export_status/?cache_key=ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11

While the job runs, is_ready stays false and url stays null. When the job finishes, the response carries the download URL:

{
    "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11",
    "is_ready": true,
    "url": "https://<cdn-host>/exports/basket_export_321a4268.xls",
    "error_message": null
}

A failed job also reports is_ready as true, but url stays null and error_message describes the failure:

{
    "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11",
    "is_ready": true,
    "url": null,
    "error_message": "Storage error"
}

Treat any response where is_ready is true and url is null as a failed export. Start a new export rather than retrying the same cache_key.

An unknown or expired cache_key returns 404 Not Found:

{
    "cache_key": "ace40858-1c3f-4c1a-9f0d-7b2c9b2f9a11",
    "is_ready": false,
    "url": null,
    "error_message": "Export not found or expired"
}

A request without the cache_key parameter also returns 404 Not Found, with an empty response body.

Poll this endpoint until is_ready is true. The export is a queued background job, so the time to completion depends on the size of the result set and on the current load of the queue rather than on a fixed duration. The API defines no polling interval; choose one that suits your integration and stop polling when the one-hour window described below expires.

Note: A large export is split across sheets named Sheet1, Sheet2, and so on. Each sheet carries its own header row and up to 65,534 records. Read every sheet in the file. Reading only the first sheet silently drops every record beyond it.

Warning: The export status expires one hour after the job finishes. After that, export_status returns 404 Not Found for that cache_key and you must start a new export. Download the file within that hour, or store its URL.