Syncing Catalog & Products

You will need to create at least one catalog to integrate with CitrusAd.

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, 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 stores, territories, or countries for campaign targeting.

If you are considering creating multiple catalogs, contact CitrusAd to discuss best practices. 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, only products relevant to the catalogs the advertiser selected are displayed for selection. Products should not be used to represent any more than a single product GTIN. Variations of the same product should be different products.

For example:

200ml, 600ml, and 2L variations of the same drink product would be regarded as 3 different products in the CitrusAd.

This is commonly aligned with existing integrator practices.

Product Properties

Each product has an an individual series of properties applied to it. The filters applied to each product will depend on the quality of integration each integrator wishes to complete.

The specific terms used differentiates between syncing via API or file. Integrators are required to sync GTIN, Name,Inventory,Description andFilters. Additional properties can be used for targeting, relevancy and platform targeting features. The GTIN property can be substituted for any unique code or SKU used in the integrator's back end.

Product Filters Explained

Product filters are used in primarily in 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, this ensures relevant ads are served to each page.

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

A context containing productFilters:

"productFilters": [

Will only return ads for products containing all filters in the relevant array. Like below:


Category Minimum Bid Filter Structure

There are no strict rules defining the structure of filters, it is up to integrators to define how they are structured. In the event the integrator enable category minimum bids, relevant category product filters are leveraged and mapped to a minimum bid value. It is best practice to ensure category filters are human readable to reduce confusion for advertisers creating campaigns.

If you are looking to utilise category minimum bid values, it is best to ensure categories are human readable and understandable for advertisers creating campaigns. category:Keyboards is easier to understand than category:12.

Providing Image and Product Name

CitrusAd needs information about product image and name to make them searchable for in the CitrusAd portal when creating campaigns. These values can be sent to CitrusAd inside filters formatted like:

"imageurl:","name:product name"

They are seen in various areas of the CitrusAd portal such as product selection below:

Syncing Catalogs & Product

You can sync your catalogs and products with CitrusAd in two ways, via our API or File. Creating catalogs and syncing products are two separate API pushes, a catalog and its products are synced with a single file.