> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/feature-integrations/category-cross-sell/integration-requirements.md).

# Integration requirements

## High-level overview

As part of this integration, you will need to do the below

1. Implement an additional ad request for the cross-sell category placement.
   1. This includes the work to position and render ads on your site, as well as report clicks and impressions
   2. Orders need to be provided to Epsilon Retail Media as part of your standard integration
2. If you synchronise category IDs with Epsilon Retail Media, you will need to use the [filterMapping](/retail-media-interface/integration/citrus-filter-mapping-api/filtermapping.md) API to provide human readable values for the UI category selection
   1. This only applies if you are integrated with category IDs instead of names. (such as when you request ads, your filters is `category:123j-dsef-er` instead of `category:Milk`
3. (Advised) - synchronise category cross-sell mappings, to automate approval and reduce campaign management load.

## Ad request and site integration

### Ad request

As category cross-sell requires a standalone placement, you will need to integrate an additional ad request per ad-type you are integrating category cross-sell for.

The format of your request should match the cross-sell category ad request as listed below

* [Product ad - requesting category cross-sell ads](/retail-media-interface/integration/generating-ads/product-ads/requesting-product-ads-1.md#cross-sell-category-placements)
* [Banner ad - requesting category cross-sell ads](/retail-media-interface/integration/generating-ads/banner-ads-static/requesting-banner-ads.md#cross-sell-category-placements)
* Banner X - requesting category cross-sell ads

### Reporting impressions and clicks

Once you have integrated your ad request, you will also need to ensure you are reporting clicks and impressions correctly for each ad shown. Ensure you read [Reporting impressions & clicks](/retail-media-interface/integration/data-api/api-overview/reporting-impressions-clicks.md).

### Reporting orders

Generally, most integrations report all order information to Epsilon Retail Media as per a standard integration. You need to ensure you are reporting all orders correctly to Epsilon Retail Media as per [Order data](/retail-media-interface/integration/data-api/order-data-1.md).

## Filter mappings

The filter mapping endpoint can be used to map your category IDs to human readable values. This is required if you synchronise category IDs as the UI shows the values to your users.

{% hint style="info" %}
If you synchronise human readable categories in your product catalog with Epsilon Retail Media, this step will not be required.
{% endhint %}

Users will not understand what `category:12345-abcde` is. The filterMapping API can be used to map the value to the relevant category name on your site, such as `category:Pantry`.

There is no file based method to synchronise this information, it must be done via the [filterMapping](/retail-media-interface/integration/citrus-filter-mapping-api/filtermapping.md) API.

{% hint style="warning" %}
As you create additional categories on your site, you will need to ensure the filterMapping API is used to update categories.
{% endhint %}

## Category cross-sell mappings (advised)

It is strongly advised when integrating this type of placement, to provide a mapping of which categories are allowed to target each other. This can streamline your operations after the initial integration work. Advertiser experience is streamlined to only allow categories that are already allowed to be selected.

In addition, it is also possible to configure auto approval for cross-sell category campaigns, when cross-sell mappings are provided.

### Integration methods

* You are able to use the [crossSellCategory](/retail-media-interface/integration/crosssellcategory-api/crosssellcategory.md) API to create and manage mappings as you require.
* Alternatively, you are able to provide a TSV file to a GCS bucket hosted by Epsilon Retail Media with the format listed below.

#### API integration

All required information can be seen in the [crossSellCategory](/retail-media-interface/integration/crosssellcategory-api/crosssellcategory.md) API reference.

#### File integration

If integrating by file, Epsilon Retail Media requires a file per catalog, of which categories are allowed to target between each other.

Each row in the file represents a single mapping of a category, and the category that it can target. Each mapping is single-directional (if you synchronise chocolate -> milk, chocolate products can appear on the milk category. If milk products need to be able to appear on chocolate, and additional row is required).

We need a data feed in TSV format aligning with the below specifications:

| column name         | Required | Datatype | Description                                                                                                         | Example            |
| ------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `category`          | Required | Text     | This is a unique category ID identifying the category of the advertised product.                                    | `category:cookies` |
| `cross_category_id` | Required | Text     | This is a unique category ID identifying an eligible category that products of category\_id can be cross sold into. | `category:milk`    |

Additional file specifications are below:

* TSV files are only supported
* TSV should be in LF not CRLF
* TSV should be UTF-8 encoded, any types will cause feed to fail
* Naming convention required: `^cross_sell_category.*.tsv$`

An example snippet looks like the below:

| category         | cross\_category\_id |
| ---------------- | ------------------- |
| category:cookies | category:milk       |
| category:cookies | category:chocolate  |
| category:milk    | category:cookies    |

This snippet above allows the **cookies** category to cross-sell into the **milk** and **chocolate** categories. The **milk** category can cross-sell into the **cookies** category. The **chocolate** category can be targeted, but cannot target any other categories.

{% hint style="danger" %}
️ Each row is a unique mapping combination

You need to synchronise unique rows for each unique cross-sell category mappings. Attempting to synchronise multiple cross\_category\_id in a single row, the file ingestion will fail.
{% endhint %}

{% hint style="warning" %}
Column order

Please ensure your file has the `category` column as the first column. If you synchronise `cross_category_id` as the first column, ingestion will fail.
{% endhint %}

## Feature activation process

Once you are ready to start synchronising your suggested search term feed, Epsilon Retail Media will configure you a GCS bucket to drop your files into.

This capability is only supported on GCS buckets. External buckets such as AWS/Azure/other are not supported.

Your Technical Account Manager will be able to guide you through the activation of this feature. As Epsilon Retail Media's platform operations team are required to action a configuration, please be advised there is an additional turnaround time for activation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/integration/feature-integrations/category-cross-sell/integration-requirements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.