---
title: "Retailer listings"
description: "The retailer listings endpoint: parameters, live and historic requests, paging and choosing fields."
canonical_url: "https://www.eebz.com/support/api/retailer-listings"
---

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](/support/api) 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**.

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        geography_ids
      </code>
    </td>
    
    <td>
      integer<span>
        
      </span>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      IDs of the territories to fetch listings from
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      string (ISO 8601)
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Start of a historic date range. Needs <code>
        to
      </code>
      
      . No more than 2 weeks before <code>
        to
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        to
      </code>
    </td>
    
    <td>
      string (ISO 8601)
    </td>
    
    <td>
      No
    </td>
    
    <td>
      End of a historic date range. Needs <code>
        from
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        limit
      </code>
    </td>
    
    <td>
      integer
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Maximum results. Defaults to 50,000 (live) or 5,000 (historic).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        page
      </code>
    </td>
    
    <td>
      integer
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Page offset for paged results.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        retailer_importance
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Filter by importance: <code>
        "AAA"
      </code>
      
      , <code>
        "AA"
      </code>
      
      , <code>
        "A"
      </code>
      
      , <code>
        "B"
      </code>
      
      , <code>
        "C"
      </code>
      
      . Needs a retailer selection in API settings.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fields
      </code>
    </td>
    
    <td>
      string<span>
        
      </span>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Return only these fields. Takes top-level keys and dotted paths, such as <code>
        "sku.gtin"
      </code>
      
       or <code>
        "contracts.monthly_price"
      </code>
      
      . Without it, the default fields from API settings are returned, or every field if no defaults are set.
    </td>
  </tr>
</tbody>
</table>

## Live request

Without `from` and `to`, the API returns today's data.

```text
{
  "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.

```text
{
  "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"`.

```text
{
  "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](/support/api/response-fields).

## Choosing fields

`fields` cuts the response down to what you need. Use dotted paths for nested fields:

```text
{
  "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](/support/api/error-codes).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.