Skip to main content

​
Introduction

A brand is a collection of products marketed and sold under a unified name. The brands associated with an account define the products that the account can promote on retailer sites. An account can have access to one or more brands, and this access is typically managed by Criteo. Brand attributes are standardized across retailers to ensure consistency.

​
Endpoints

Method

Endpoint

Description

GET

/accounts/{accountId}/brands

Get Brands

POST

/brands/search

Search for Brands by name in Retailer(s)Catalogs

​
Brand Attributes

Attribute

Data Type

Description

id

string

Brand ID, generated internally by Criteo and originated from brand name provided in retailer’sCatalog

Accepted values: int64

Writeable? N / Nullable? N

name

string

Brand name, keyword to use as filter in the search (case-insensitive) or returned as final brand name available

Accepted values: string

Writeable? N / Nullable? N

retailerIds*

list

List ofRetailerIDs, to use as filter in the search or returned as containing the specific brand

Accepted values: list of strings of int32

Writeable? N / Nullable? N

brandType

enum

Type of brands, to consider in the search or returned as attribute of the specific brand

  • all: all brands
  • retailer: brands specific to the retailer
  • uc: brands referenced to our Universal Catalog

Accepted values:all,retailer,uc(case-insensitive)

Default:all

Writeable? N / Nullable? N

(*) Required
Field Definitions
  • Writeable (Y/N): Indicates if the field can be modified in requests.
  • Nullable (Y/N): Indicates if the field can accept null/empty values.
  • Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., retailerId, campaignId, lineItemId) and are usually required in the URL path.

​
Get all Brands

This endpoint lists all brands associated with an account. Results are paginated using pageIndex and pageSize query parameters; if omitted, defaults to 0 and 25, respectively. See API Response.

​
Sample Request

curl -L -X GET "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/brands?pageIndex=0&pageSize=25" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

​
Sample Response

{
    "data": [
        {
            "id": "7672171780147256541",
            "type": "RetailMediaBrand",
            "attributes": {
                "name": "Brand 123"
            }
        },
 
        // ...
 
        {
            "id": "5979998329674492121",
            "type": "RetailMediaBrand",
            "attributes": {
                "name": "Brand 789"
            }
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 15,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}

​
Search for Brands by name

This endpoint searches for Brands, by name term, across one or multiple retailers. Results are paginated.

​
Sample Request

curl -L -X POST 'https://api.criteo.com/{version}/retail-media/brands/search?offset=0&limit=25' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
    -d '{
            "data": {
                "type": "<string>",
                "attributes": {
                    "retailerIds": [
                        "123",
                        "456"
                    ],
                    "name": "brand abc",
                    "brandType": "all"
                }
            }
        }'

​
Sample Response

{
    "metadata": {
        "count": 2,
        "offset": 0,
        "limit": 25
    },
    "data": [
        {
            "id": "2149023412134133",
            "type": "BrandIdSearchResult",
            "attributes": {
                "id": "2149023412134133",
                "name": "brand abcdef",
                "brandType": "Retailer",
                "retailerIds": [
                    123
                ]
            }
        },
        {
            "id": "62342",
            "type": "BrandIdSearchResult",
            "attributes": {
                "id": "62342",
                "name": "Brand ABC",
                "brandType": "UC",
                "retailerIds": [
                    123,
                    456
                ]
            }
        }
    ],
    "warnings": [],
    "errors": []
}

​
Responses

Response

Error

Message

Description

🟢200

Call completed successfully

🔴400

Validation Error

One or more validation errors occurred.

One of the parameters provided in the request does not match the format accepted. Check the error details and the parameters informed in the call

🔴403

Authorization Error

Resource access forbidden: does not have permissions

API user does not have the authorization to make requests to the account ID. For an authorization request, follow theauthorization requeststeps

​
What’s next