Partner API
API Reference

Catalog & Products

To integrate with CitrusAd, you will need at least one catalog of products.

What is a catalog?

A catalog is a grouping of products and their attributes, most commonly used to group all products of an integrator's site into one single catalog.

Catalogs are selected by advertisers in the campaign creation process, and their campaigns will only run within their selected catalog of products. It is common practice for all products to be grouped into a single catalog for an integrator, making selection simple for advertisers.

Creating multiple catalogs can be used to segment product availability in different retailers or countries for campaign targeting purposes.

📘

If you want to create multiple catalogs, contact your Technical Account Manager to discuss best practices, as there may be better-supported ways to implement targeting.

🚧

If you are integrating into a network namespace, you should create a single catalog.

What are products?

Products are individual GTIN's on an integrator's site. Products synced with CitrusAd are synced with individual identifying values and attributes. Products should represent each GTIN/SKU in your current product catalog.

Products are selected by advertisers in campaign creation, with only the products relevant to the catalogs the advertiser selected displayed for selection. Products should not be used to represent any more than a single product GTIN. Variations of the same product should be listed as different products, e.g. 200ml, 600ml, and 2L variations of the same drink product would be regarded as three different products in CitrusAd, aligning with existing integrator best practices.

Product filters explained

Product filters are primarily used for ad generation in addition to containing properties such as imageUrl and name. When requesting ads from CitrusAd, you will send a context containing relevant page information which ensures relevant ads are served to each page.

The structure of filters is up to the integrator, but the most important thing to consider is that these product filters will be sent in your ad generation context. Product filters should match exactly with what is being requested in ad generation.

An example context containing productFilters is outlined below:

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
}

This context will only return ads for products containing all filters in the relevant array.

📘

If you want to utilise category minimum bid values, make sure your categories are user-friendly and easy for advertisers creating campaigns to understand, e.g. category:Keyboards is easier to understand than category:12.

Providing images and product names

CitrusAd needs information about product images and names to make them searchable when creating campaigns in the CitrusAd portal. These values can be sent to CitrusAd inside tags formatted like the following 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"
            ]
        }
    ]
}

They are seen in various areas of the CitrusAd portal including product selection, like the example below:

1581

Reference image