Retailer listings
The retailer listings endpoint: parameters, live and historic requests, paging and choosing fields.
Send a POST request with a JSON body to the request URL shown in Settings › Organisation › General › Export API. It returns listing data (pricing, availability and product details) across your retailers. See the API overview for authentication.
Request body
Send parameters as a JSON object. Only geography_ids is required.
In the app these are your territories. The API calls them geographies, so geography_ids takes territory IDs. Find each territory's ID in Settings › Organisation › General › Export API.
| Parameter | Type | Required | Description |
|---|---|---|---|
geography_ids | integer | Yes | IDs of the territories to fetch listings from |
from | string (ISO 8601) | No | Start of a historic date range. Needs to. No more than 2 weeks before to. |
to | string (ISO 8601) | No | End of a historic date range. Needs from. |
limit | integer | No | Maximum results. Defaults to 50,000 (live) or 5,000 (historic). |
page | integer | No | Page offset for paged results. |
retailer_importance | string | No | Filter by importance: "AAA", "AA", "A", "B", "C". Needs a retailer selection in API settings. |
fields | string | No | Return only these fields. Takes top-level keys and dotted paths, such as "sku.gtin" or "contracts.monthly_price". Without it, the default fields from API settings are returned, or every field if no defaults are set. |
Live request
Without from and to, the API returns today's data.
{
"geography_ids": [1, 2],
"retailer_importance": ["AAA", "AA"],
"fields": ["sku.gtin", "price", "availability"]
}
Historic request
Set from and to for a date range of up to 2 weeks.
{
"geography_ids": [1],
"from": "2025-01-01T00:00:00Z",
"to": "2025-01-14T00:00:00Z",
"limit": 5000,
"page": 0
}
Response
A successful request returns a JSON array: a paging object followed by listing objects. If nothing matches, it returns the string "no_data_found".
{
"total_pages": 10,
"current_page": 0,
"last_page": false
}
Request the next page with page until last_page is true. Each listing object holds the fields in response fields.
Choosing fields
fields cuts the response down to what you need. Use dotted paths for nested fields:
{
"geography_ids": [1],
"fields": ["sku.gtin", "price", "availability", "contracts.monthly_price"]
}
Without fields, the API returns the default fields set in API settings, or every field if no defaults are set.
If a request fails, see error codes.
Last updated October 2026