> 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/suggested-keywords.md).
# Suggested Keywords
**Suggested keywords** tie **search terms** to **product codes** in your catalog. When advertisers build campaigns, those terms appear during **Targeting** (search keyword selection) for the products they add. Advertisers can pick from suggestions instead of typing only custom keywords, which improves alignment with how your site indexes search and how you want campaigns to map SKUs to queries.
**Suggested keywords can be supplied in two ways:**
1. **Epsilon AI-generated keywords** — Epsilon generates, classifies, and loads product–keyword pairs on your behalf. You are **not required** to maintain a separate keyword file for those suggestions when this path is your sole source. Generation uses product and catalogue context, shopper search behaviour, and signals aligned to your **retailer business rules** (for example brand conquesting and other programme constraints).
2. **Retailer-managed TSV feed** — You synchronise a file that maps each `product_code` to one or more `search_term` values, with optional rank and type. You manage the suggested keywords per product.
Retailers can choose to use **Epsilon generated keywords only**, **your file only**, or **both** (for example AI suggestions **overlaid** on an existing list, or a coordinated **replace** during rollout so existing approvals are handled deliberately).
If Epsilon is supplying **AI suggested keywords** for your programme and you do **not** need a retailer TSV feed, start with [**Step 3: Activate AI suggested keywords (beta)**](#step-3-activate-ai-suggested-keywords-beta). Use [**Step 2: Build the TSV file**](#step-2-optional-build-the-tsv-file-retailer-supplied-path) only when you maintain or supplement keywords via file.
### Why use suggested keywords?
* Steer advertisers toward high-intent, product-accurate search terms
* Surface terms advertisers might not think of without guidance
* Increase competition on valuable keywords while staying within programme rules
* Reduce manual file work when AI generation is enabled
**This guide covers**
* Prerequisites and end-to-end flow
* API authentication for read/validate flows
* Step-by-step AI activation (beta) and optional TSV implementation
* Sandbox testing, go-live checklist, troubleshooting
### Serving rules
When advertisers add **suggested** keywords to a campaign, **only products linked to that keyword** are eligible to serve on matching customer search terms.
The UI shows which products map to which suggested keywords:
**Custom** search terms chosen by the advertiser typically apply across campaign products according to placement rules; **suggested** selections restrict eligibility using the **retailer / Epsilon** mapping.
## Prerequisites
Use this checklist before you start.
* [ ] **Retailer** onboarded (or in progress) with Epsilon Retail Media, including catalog sync.
* [ ] **Sandbox access** to the campaign UI and APIs where you will validate keywords (when available for your programme).
* [ ] **For TSV delivery:** GCS bucket (or path) **provisioned by Epsilon**, and credentials your team can use to upload objects (method confirmed with Epsilon—often service account key or federated access). Note if you are only scoping, this is handled as part of the activation process if you are supplying keywords.
* [ ] **Technical contact** who can upload files, run API checks, and coordinate with Epsilon on ingestion schedules and cutovers.
* [ ] **Release awareness:** per-keyword product eligibility for suggestions requires platform (see Serving rules above).
***
## Integration Flow Overview
1. You confirm with Epsilon how keywords will be supplied: **Epsilon generated**, **TSV file**, or **both**.
2. If you are providing a file, upload it to the GCS bucket provisioned by Epsilon.
3. Epsilon enables the capability and (for files) ingests your file. For **AI** keywords, Epsilon aligns on rules, optional overlay vs replace, and staging validation.
4. Data lands as **suggested keywords** in the platform.
5. You **verify** in your sandbox directly in the UI prior to launch to your advertisers.
6. You **go live** in production and tell advertiser teams that suggested keywords are available.
***
## Step-by-Step Implementation Guide
### Step 1: Confirm your supply model with Epsilon
**Purpose**\
Avoid building a file pipeline if **AI-only** meets your needs, or avoid duplicating work if Epsilon will overlay/replace lists for you.
**What you need to do**
* Decide: **AI only**, **TSV only**, or **both**.
* Confirm **overlay** vs **replace** for any existing suggested-keyword data.
* Confirm which **placements** exist (`ORGANIC` only vs also `CROSS_SELL` / `SUBSTITUTE`).
***
### Step 2: Activate AI suggested keywords
**Purpose**\
Get Epsilon-generated, rule-filtered keywords into the platform **without** maintaining a TSV.
**What you need to do**
1. **Engage Epsilon** — Provide your specific **business rules** (for example brand conquesting), and how new data should relate to existing lists if you already sync suggested keywords (**overlay** vs **replace**).
2. **Test in sandbox** — Work with Epsilon to load or review keywords in **staging/sandbox**. Dry-run **Targeting** in the campaign UI: pick products and confirm suggested phrases look correct.
3. **Production** — After sign-off, Epsilon enables production. **You** communicate to advertiser teams that suggested keywords are live (the UI will show them once enabled).
**How AI Keyword suggestions work**
1. **Understand the product** - Modelling uses product intent, retailer context, and language.
2. **Generate keywords** - Candidate keywords are produced from that understanding.
3. **Classify** - Keywords are selected using ad and search data so programme rules (for example brand conquesting or retailer-specific policies such as targeting the ingredients of a product) are respected.
4. **Load for the UI** — Product–keyword pairs are stored in the same system used by the **suggested keyword** flow in campaign setup.
**Governance**
* Approval behaviour (**auto vs manual retailer review**) depends on **programme configuration** agreed with Epsilon.
* If you have **little ad-query history**, you may be asked to share a **short sample of organic on-site search requests** (for example about **seven days**) so generation matches real shopper language.
* **Very large catalogs** may scope generation to products with **recent advertising activity** (for example about the **last 90 days**) instead of every SKU—confirm with Epsilon.
* **AI-generated suggested keywords (beta)** currently focus on **organic** search use cases; support for additional placement types may expand.
**Validation**
* Suggested keywords appear in sandbox **Targeting** for products in scope.
* Approval behaviour (auto vs manual review) matches programme configuration.
**Common errors**
| Error | Fix |
| ---------------------------------------- | ---------------------------------------------------------------- |
| Keywords look off-brand or off-policy | Refine business rules with Epsilon and re-run sandbox review |
| Few or no suggestions for large catalogs | Confirm whether generation is scoped to recently advertised SKUs |
***
### (Optional for Step 2): Build your TSV file (retailer-supplied path)
**Purpose**\
Supply authoritative **product\_code → search\_term** rows (and optional rank/type).
**What you need to do**
* Generate a tab-separated file of product and keyword linkages.
* Use **UTF-8** encoding and **LF** line endings.
* Include a header row that matches the field names your feed specification uses; at minimum: `product_code`, `search_term`, `search_term_type`. See [Data Models & Field Definitions](#data-models--field-definitions).
* Keep around **\~20 suggested keywords per product** for usability.
* Repeat `product_code` on multiple lines for multiple terms; use `**search_term_type`\*\* when you have multiple placement kinds.
* Validate the file, then deliver it to the GCS bucket Epsilon provisions.
**Note:** When you synchronise a retailer feed, Epsilon Retail Media provisions a **GCS bucket** for drops. Platform operations must finish configuration—allow turnaround time for activation.
**Example file (snippet)**
```
product_code search_term search_term_rank search_term_type
abc123 cereal 1 ORGANIC
abc123 cereals 2 ORGANIC
12345 milk 1 CROSS_SELL
```
**Validation**
* Open in a text editor: fields separated by **tab**, no stray CR-only line endings.
* Spot-check several `product_code` values exist in your **catalog** feed.
**Common errors**
| Error | Fix |
| -------------------------- | ----------------------------------------------- |
| CSV commas instead of tabs | Re-export as TSV |
| Wrong product IDs | Align with `gtin` / `item` used in catalog sync |
| Too many lines per SKU | Trim to the highest-value terms |
***
### Step 3: Verify suggestions in the UI
**Purpose**\
Catch last-minute mapping issues before production.
**What you need to do**
* In **sandbox**, create or edit a campaign, select placements that support suggested keywords, add products, open **Targeting** / keyword selection.
* Confirm suggested phrases per product and that **custom** vs **suggested** behaviour matches your expectations (see \*\*Serving rules in **Overview**).
* Confirm **suggested** selections restrict eligible products to those linked in your feed or AI pipeline.
**Validation**
* In your sandbox UI: suggested keywords appear for products linked to keywords in your file or AI pipeline.
* Suggestions align to placement and catalog expectations.
**Common errors**
| Error | Fix |
| ------------------------------- | -------------------------------------------------------- |
| Suggestions only on one catalog | Backfill other catalogs or adjust campaign catalog scope |
| Wrong placement type showing | TAM reviews placement ↔ `search_term_type` configuration |
***
## Data Models & Field Definitions
### TSV (retailer file)
| Field | Type | Required | Description | Accepted values |
| ------------------ | ------- | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `product_code` | string | Yes | Retailer product identifier; same as catalog `gtin` / `item` where applicable | Non-empty; must exist in synced catalog |
| `search_term` | string | Yes | Keyword or phrase suggested for the SKU | UTF-8 text; avoid control characters |
| `search_term_rank` | integer | No | Relative relevance; **1** is highest | Positive integers; lower = higher priority |
| `search_term_type` | string | No | Maps rows to **placement** kinds | `ORGANIC`, `CROSS_SELL`, `SUBSTITUTE`; default treated as `ORGANIC` if omitted |
| (line endings) | — | — | File format | **LF**; file encoding **UTF-8** |
### Placement types and `search_term_type`
`search_term_type` aligns with placement types: **ORGANIC**, **CROSS\_SELL**, and **SUBSTITUTE**.
Most retailer programmes use a single **organic search** placement for standard search results ads. **CROSS\_SELL** and **SUBSTITUTE** are **separate placements** on the search page (or related inventory) with different serving intent—they are not just extra columns in the same organic auction. Your Technical Account Manager confirms which placements exist for your namespace.
**How placement types differ**
* **Organic** — Ads matched to the shopper's search intent for the product (for example a cola product on "cola").
* **Cross-sell** — Complementary intent (for example pizza on "cola").
* **Substitute** — Similar-product intent (for example another cola variant on "cola").
You can synchronise **one feed per placement type** or **combine types in a single file** (repeat `product_code` with different `search_term_type`). Your Technical Account Manager configures placements so the correct suggestion type appears per surface. Suggested keywords can be **shown or hidden per placement**.
Combined types for one product:
| product\_code | search\_term | search\_term\_rank | search\_term\_type |
| ------------- | ------------ | ------------------ | ------------------ |
| 12345 | cookies | 1 | ORGANIC |
| 12345 | cookie | 2 | ORGANIC |
| 12345 | milk | 1 | CROSS\_SELL |
**Note:** Most programmes only use **organic** search placements. `CROSS_SELL` and `SUBSTITUTE` correspond to **additional placements**, not "extra columns" in the same organic slot—confirm which placements you operate with your Technical Account Manager.
### Multiple catalogs
Implement suggested keywords across **all** catalogs in your namespace when possible (whether from your feed, AI generation, or both). This reduces brand confusion when one catalog has suggestions and others do not.
For multi-catalog campaigns, if only one catalog has data, campaigns that depend on suggested selections only behave fully on that catalog.
\##
***
## Testing, Sandbox, and Go-Live
**Sandbox / test environment**
* Validate UI suggestions in the campaign **Targeting** step.
**Sample test cases**
| Test | Steps | Expected result |
| ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------- |
| UI suggestions visible | Add products in sandbox campaign; open **Targeting** | Suggested keywords appear per product |
| Serving rule | Select a suggested keyword linked to subset of products | Only linked products eligible for that term |
| Multi-catalog coverage | Repeat UI check across catalogs in namespace | Suggestions present on all catalogs with data (or scope documented) |
**Go-live checklist**
* [ ] TSV ingested without errors (if using file path) or AI pipeline signed off (if using beta)
* [ ] Suggested keywords visible in sandbox UI for representative products
* [ ] Multi-catalog namespaces have coverage on all catalogs (or scope documented)
* [ ] Advertiser communication sent before or at production enablement
* [ ] Partner API returns expected rows in production (spot-check)
***
## Troubleshooting & FAQ
**Problem:** Suggestions never appear in the UI.\
**Likely cause:** Ingestion not enabled, wrong catalog, or placement not configured.\
**Solution:** Confirm with Epsilon that GCS ingestion or AI pipeline is active; verify placement mapping for `search_term_type`.
**Can we use one TSV for multiple placement types?**\
Yes. Repeat `product_code` on multiple lines with different `search_term_type` values. Your Technical Account Manager configures which types surface per placement.
**What if we have multiple catalogs in one namespace?**\
Implement suggested keywords across all catalogs when possible. Campaigns that depend on suggested selections only behave fully on catalogs with data.
**When contacting support, include:**
* Namespace and catalog ID
* Sample `product_code` and expected `search_term`
---
# 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/suggested-keywords.md?ask=&goal=
```
`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.