Retrieve Products

To be able to look for products in your catalogue, you need, as a prerequisite, to get an access token.
The steps to get a token are described in the Authentication and tokens page.

Once you are authenticated, you are able to look for your products in your catalogue

Retrieve your first Product

Now that you are authenticated, to get your first product, take one of the gtin of your SupplierXM catalog.

# Get product
filter_payload = {
    "filter_gtins_in": ["03036811359935"], # update with one of your gtin
    "filter_source_include": ["gtin", "nameLegal"], # retrieve only 2 fields

# Call the products API
response =
  headers=headers # previously set with authentication token

# Response contains:
# {"data": [{"gtin": "03036811359935", "nameLegal":[{"expressedIn": {"code": "eng-GB"}, "data": "My first product"}]}]}

# Iterate on the product list
for product in response.json()['data']:
    # Retrieve the data in english
    nameLegal = next((n['data'] for n in product.get('nameLegal', []) if n['expressedIn']['code'] == 'eng-GB'), None)
    print '%r -> %r' % (product.get('gtin'), nameLegal)

# >> '03036811359935' -> 'My first product'
>> replace 03036811359935 with your own gtin :)
>> add your access token to the HTTP header 

curl '' -XPOST -d'{"filter_gtins_in":["03036811359935"],"filter_source_include": ["gtin", "nameLegal"]}' \
-H 'Authorization: Bearer {your access token}'

>> {
  "totalResults": 1,
  "data": [
      "nameLegal": [
          "expressedIn": {
            "code": "eng-GB",
          "data": "My first product"
      "gtin": "03036811359935",
  "offset": 0

List/search/filter Products

Two methods are available to retrieve products according to the use case:

  • GET: to retrieve one or more products: List Product
    For this method, a limit is set to 500 products if there is no filtering on fields, and to 4000 products if there is filtering (filter_source_include)

  • POST: to retrieve a large number of products: Search Product

In order to filter the products on a specific organization, you need to use the services with additional filters:

filter_owners_in allows you to specify the organization identifier

filter_target_market allows you to request only product sold in France. (market code : 250, see ISO-3166 numeric country codes for more information).

limit allows you to set the maximum number of products you want to retrieve. By default the limit parameter is set to 20. The max value is 500. To optimise performances we advice you to use a limit at 50 and then make multiple consecutive calls using offset parameter for pagination.

filter_source_include allows you to retrieve only some fields by specifying the list of fields. We strongly encourage you to use this filter to have better response times by restricting the amount of data returned to what is really necessary

To retrieve more than 10K elements you need to use "scroll search" by doing the following:

  • on the first call, set next_page to "" (empty string in double quotes for POST request, nothing for GET request) and set the limit (50 for instance) (offset parameter will be discarded)
  • on the following calls, pass the next_page parameter with the value returned by the previous call (next_page changes after each call). You still need to pass a limit parameter (you can actually change it after each call, but it's recommended not to change it)
  • you have 2 minutes between each calls to make the following call, after this, the next_page will be invalid and you will have to restart from the beginning (ie: set next_page to '')


Choose the best pagination method

In order to choose the best pagination method you should use, you can make a first call to get the number of products matching your request.

Make a first call with all the filters to apply for the products you want to retrieve and set the parameters limit to 1 and filter_source_include with 1 specific field like UUID (to optimize the call).

curl --request GET \
  --url '' \
  --header 'Accept: application/json' \
  --header 'Accept-language: fr' \
  --header 'Authorization: Bearer AUTHORIZATION_TOKEN'

In the response, you will get a totalResults field showing you how many products matches your request and be able to choose the suited pagination method.


Retrieve assets

All media information can be retrieved in the payload in the "assets" key.
It contains information for each media type:

  • Images information are in the "pictures" key
  • Document information is in the "document" key
  • Video information is in the "videos" key

For each media, metadata are provided to describe it: angle, face, tags, main picture, etc…

Link to media documentation: Media assets

API References

public/v1/products: Retrieve Products