You can use the APIs to update product details, including product code, price, inventory details, image URL, and more. Additionally, you can also update location information and High Fat, Sugar, and Salt (HFSS) information as well.

Prerequisites

You must have API keys and the base URL before requesting to create catalogs.

You must have a valid API key. To fetch the API keys, do the following:
1. Log into your Epsilon's Retail Media team account.
2. Navigate to the top right of the page and click on the drop-down menu.
3. Select Integration Settings, from the drop-down menu.
4. Click on the API Key tab. Your secret API key is initially hidden. To view it, click on the Show button. Once it becomes visible, copy your secret API key. Use this key for making API calls.
You must have the Base URL for the API endpoint. For example, https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Check with your Technical Account Manager for the Base URL.

Standard Context to Add Products

Once your catalog is created, you can synchronize products to it using the API. The following example demonstrates the standard context to add products.

Request Parameters

The following are the query and body parameters:

Query Parameter

Object	Type	Description
teamId	string, optional	ID of your team. If a `teamId` is not provided, it will default to the `teamId` specified in the authentication.

Body Parameter

Object	Type	Description
catalogId	string, required	Identifier for the catalog to which the product belongs.
gtin	string, required	Global Trade Item Number (GTIN) for the product.
inventory	number, optional	Inventory count for the product.
price	number, optional	Price of the product.
categoryHierarchy	array of strings, optional	Hierarchy of categories to which the product belongs.
tags	array of strings, optional	Tags associated with the product.
filters	array of strings, optional	Filters applied to the product.

Request Example

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
            ]
        }
    ]
}

Request Response

{
    "catalogProducts": [
        {
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": 19.99,
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0"
            ],
            "groups": [],
            "profit": null
        }
    ]
}

Update Location Information

You can also update filters for various store locations where your products are available. This feature is useful for optimizing product information at the store or location level.

Request Example

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0","location:123","location:ABC"
            ]
        }
    ]
}

Response Example

{
    "catalogProducts": [
        {
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": 19.99,
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0",
              	 "location:123",
              	 "location:ABC"
            ],
            "groups": [],
            "profit": null
        }
    ]
}

Update HFSS Information

To include HFSS (High Fat, Sugar, and Salt) information in your product update, you need to send a filter with the value hfss:true or hfss:false. This allows Epsilon Retail Media to appropriately filter the interface based on HFSS criteria.

Request Example

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "hfss:true","category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0","location:123","location:ABC"
            ]
        }
    ]
}

Add Multiple Products

When updating multiple products, you can process up to 100 items per request. The following example illustrates the context for updating two products.

Request Example

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0"
            ],
            "profit": "1.50"
        },
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965738",
            "inventory": 26,
            "price": "8.50",
            "tags": [
                "imageurl:https://your.image.host.com/image.jpg",
                "name:Kelloggs Froot Loops Breakfast Cereal 500g"
            ],
            "filters": [
                "Brand:Kelloggs",
                "category:Pantry",
                "category:BreakfastFoods",
                "category:Cereals",
                "Special_Flag:0"
            ],
            "profit": "0.50"
        }
    ]
}

Request Response

{
    "catalogProducts": [
        {
            "gtin": "23556578965543",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "price": 19.99,
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "groups": [],
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0"
            ],
            "inventory": 50,
            "profit": 1.50,
            "tags": [
                "Natural",
                "Lasting",
                "Dry Skin",
                "Beige"
            ]
        },
        {
            "gtin": "23556578965736688",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "price": 8.50,
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "groups": [],
            "tags": [
                "imageurl:https://your.image.host.com/image.jpg",
                "name:Kelloggs Froot Loops Breakfast Cereal 500g"
            ],
            "filters": [
                "Brand:Kelloggs",
                "category:Pantry",
                "category:BreakfastFoods",
                "category:Cereals",
                "Special_Flag:0"
            ],
            "inventory": 26,
            "profit": 0.50,
            "tags": [
                "Pantry",
                "BreakfastFoods",
                "Cereals",
                "Kelloggs"
            ]
        }
    ]
}

Add Product Filters

In the process of generating ads through the CitrusAd API, you may wish to apply product filters to refine your results. This can be achieved by including a productFilters field in your POST request. The productFilters field is an array that contains one or more sub-arrays, each representing a different filter.

Request Example

Here is an example of a POST request to the /v1/ads/generate endpoint that includes productFilters:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
         ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

In this example,

Two product filters are included category:Cupboard and dietary:Gluten-free. The filterMode option is set to AndOr, which means that the API will return ads for products that match both of these filters.
The returned ads will only feature products that fall under the 'Cupboard' category and are also 'Gluten-free'. The number of ads returned will not exceed the specified maxNumberOfAds, which is set to 3 in this example.

With the correct usage of productFilters, you can effectively customize the ad results to better suit your campaign needs.

Include Essential Product Images and Names

For improved searchability during the campaign creation process in the CitrusAd portal, provide product images and names. Assign the values for the images and names within the respective tags. These values are sent to CitrusAd.

Request Example

Here is an example of a POST request to the /v1/catalog-products endpoint that includes product images and names:

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 ""imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
            ]
        }
    ]
}

In the example request above, the tags field includes two key pieces of information, the image URL and the product name. imageurl and name are the keys, and they are each followed by their respective values.

imageurl:https://your.image.host.com/image.jpg provides the URL where the product image is hosted.
name: Covergirl Clean 120 Creamy Natural Liquid Foundation 30mL provides the name of the product.