Epsilon Retail Media
Sync customer profiles and catalog products to Epsilon Retail Media (CitrusAd) for targeted retail advertising campaigns. Zeotap enables you to keep your customer data and product catalog in sync with the Epsilon Retail Media platform, powering personalized ad experiences across retail media networks.
Prerequisites
- An Epsilon Retail Media (CitrusAd) account with API access
- Your secret API key (found in Integration Settings in the Epsilon Retail Media dashboard)
- Your Team ID (found in Integration Settings, changes between sandbox and production)
- Your API base URL (provided by your Technical Account Manager for staging and production)
- For product syncs: at least one catalog created in Epsilon Retail Media
Authentication
Epsilon Retail Media uses Basic Authentication with a secret API key.
- Log in to your Epsilon Retail Media dashboard
- Click the dropdown menu in the top right corner and select Integration Settings
- Click the API Key option in the secondary menu
- Click Show to reveal your secret API key
- Copy the API key and paste it into the API Key field in Zeotap
Your API key is different for sandbox and production environments. Make sure you use the correct key for the environment you are configuring.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| API Base URL | Text | Yes | Your Epsilon Retail Media API base URL. Example: https://integration-example.citrusad.com/v1 |
| Team ID | Text | Yes | Your retailer team identifier. Found in Integration Settings in the dashboard. |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Object Type | Select | Yes | The type of object to sync: Customers or Catalog Products. |
| Catalog ID | Text | Yes (for products) | The catalog identifier for syncing products. Only shown when Object Type is Catalog Products. |
Supported Operations
Sync Modes
| Mode | Supported | Description |
|---|---|---|
| Upsert | Yes | Creates new records or updates existing ones by id (customers) or gtin (products). |
| Insert | — | Not supported as a distinct mode. The Epsilon Retail Media API only exposes create-or-update semantics. |
| Update | — | Not supported as a distinct mode. The Epsilon Retail Media API only exposes create-or-update semantics. |
| Mirror | — | Not supported. |
Audience Sync Modes
Epsilon Retail Media does not support direct audience membership sync modes. Use the Customers object type with segmentIds field mapping to manage segment associations.
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
Customers
| Field | Description |
|---|---|
id | Unique customer identifier in Epsilon Retail Media. |
Catalog Products
| Field | Description |
|---|---|
gtin | Global Trade Item Number (product code) for the catalog product. |
Default Destination Fields
Customers
| Field | Type | Description |
|---|---|---|
id | string | Unique customer identifier. |
yearOfBirth | number | Customer birth year for age-based targeting. |
gender | string | Customer gender. Accepts Male, Female, Other (case-insensitive). Other values convert to Other. |
postcode | string | Customer postal code. |
suburb | string | Customer suburb or city. |
segmentIds | json | Array of audience segment IDs to associate with the customer. |
Catalog Products
| Field | Type | Description |
|---|---|---|
gtin | string | Product code or identifier. |
inventory | number | Stock level. Use 0 to mark out of stock. |
price | string | Product price. |
profit | string | Profit margin (optional). |
tags | json | Array of key:value tag strings (e.g. name:ProductName, imageurl:URL). |
filters | json | Array of filter strings (e.g. category:Health, brand:Acme, hfss:false). |
How It Works
- Authentication: Zeotap authenticates with the Epsilon Retail Media API using Basic authentication with your secret API key.
- Batch Processing: Customer records are sent in batches of up to 1,000 per API request. Product records are sent in batches of up to 100 per request (the CitrusAd API limit).
- Upsert Behavior: The Epsilon Retail Media API creates new records or updates existing ones based on the identifier (
idfor customers,gtinfor products). - Catalog ID Injection: For product syncs, Zeotap automatically includes the configured Catalog ID in every product record.
- Retry Logic: Failed requests are retried with exponential backoff for transient errors (HTTP 429 and 5xx responses).
Rate Limits
Epsilon Retail Media applies rate limits to API requests. If you encounter HTTP 429 (Too Many Requests) responses, Zeotap automatically retries with exponential backoff. Contact your Technical Account Manager for specific rate limit details for your account.
Best Practices
- Use sandbox for testing: Epsilon Retail Media provides separate sandbox and production environments. Test your sync configuration in sandbox before deploying to production.
- Keep API keys separate: Use different API keys for sandbox and production. Create separate destinations in Zeotap for each environment.
- Sync segments via customers: To associate customers with audience segments, map a
segmentIdsfield containing an array of segment ID strings. - Product tags for search: Include
nameandimageurltags for products to enable proper display in ad placements. - Filter categories carefully: Use consistent filter values (e.g.
category:Health&Beauty) across all products for reliable targeting. - Monitor inventory: Sync inventory levels regularly. Setting inventory to
0effectively removes a product from ad eligibility.
Troubleshooting
Authentication failed: invalid API key
Verify your API key in the Epsilon Retail Media dashboard under Integration Settings > API Key. Ensure you are using the correct key for the environment (sandbox vs. production). API keys are different between environments.
Base URL connection error
Confirm your API base URL is correct. The URL format is typically https://integration-{instance}.citrusad.com/v1. Contact your Technical Account Manager if you don’t have your base URL.
Team ID not found
Verify your Team ID in Integration Settings. The Team ID changes between sandbox and production environments. Ensure you are using the correct Team ID for your target environment.
Catalog products failing with 400 error
Ensure all required fields are mapped: gtin, inventory, price, and tags. Products must have at least one tag. Verify the Catalog ID exists in your Epsilon Retail Media account.
Customer gender values not accepted
The gender field accepts Male, Female, or Other (case-insensitive). Any other value is automatically converted to Other by the Epsilon Retail Media API.
Segment IDs not being applied
Ensure segmentIds is mapped as a JSON array of strings, not a single string value. Example: ["segment-1", "segment-2"]. Verify the segment IDs exist in your Epsilon Retail Media account.
Product sync processing delay
Product data ingestion in Epsilon Retail Media is not instantaneous. After a successful sync, it may take some time for updated products to appear in ad placements. This is normal platform behavior.