Welcome to the Epsilon Retail Media Partner API. This guide helps you integrate with our advertising platform to manage your campaigns, wallets, teams, and users programmatically. You can also track performance and grow your business effectively.
What is an API?
An API stands for Application Programming Interface. An API acts as the middleman allowing two software components to communicate using a set of functions and procedures. APIs are commonly used to get or send data, accessing features and services from other applications.
What is Partner API?
Our Partner API gives you programmatic access to nearly everything you can do in the Epsilon Onsite Campaign Management platforms' user interface. That means instead of manually clicking through the app, your systems or developers can connect directly to our platform and automate, customize, or integrate its features into your own tools or workflows.
The Partner API is utilized by many retailers and partners including aggregators like Pacvue, Skai and Commerce IQ.
API overview
The Epsilon Retail Media Partner API enables programmatic management of retail media Campaigns, Team & User, and Wallets. Use it to create and update campaigns across multiple ad formats including Sponsored Product Ads (SPAs), static banners, and responsive Banner X ads.
Our Partner API is a REST-based API using common GET, POST, PATCH and DELETE protocols via JSON payloads.
Key benefits
- Automate campaign, team & user, and wallet operations through REST API endpoints.
- Manage multiple campaigns and resources efficiently with bulk operation support.
- Allow you to orchestrate API calls to fit your existing workflow and system architecture.
- Create and manage campaigns across Sponsored Product Ads, Banner, and Banner X formats.
- User key-based authentication with time-limited tokens for secure API interactions.
Prerequisites
Before using the Partner API, ensure the following requirements are met:
Namespace access
You must have access to your designated namespace, which acts as a container for your data and configurations. Reach out to the Epsilon Support team to obtain namespace configuration details specific to your retailers.
Team membership
You must be part of either a supplier or primary retailer team with the appropriate permissions within your namespace.
API intake request
Ad aggregators, agencies, and brand partners must raise an API intake request before using the Partner APIs. Use the official intake form referenced in KB0040933 to initiate a new API connection.
Reporting API access
You must have access to the Reporting API (BigQuery data warehouse) to query relevant tables such as dim_product, dim_catalog, and dim_placement. This helps validate integration readiness and explore metadata.
Required metadata
Ensure your product catalog, placement, and team information are created and available under your namespace. You can verify this by querying the appropriate BigQuery tables.
If you do not have access to BigQuery, request it through the official API access request form. Depending on your needs, please refer to the appropriate knowledge base article:
- Change/Remove Reporting BigQuery API Endpoint: Need to modify an existing API endpoint - KB0040934.
- NEW Partner API (reporting API) - KB0040947.
Access Note: Some links in this document point to internal or restricted resources. Ensure you are signed in with appropriate credentials to access the content.
Getting started with Partner APIs
Authentication Requirements
Partner API utilizes an authorization process requiring a User Key. Access tokens are retrieved by calling the User Key Authentication API:
- Your retrieved User Key is passed in the header of this request.
- The retrieved Access Token is subsequently used in any method calls to the Partner API.
- Tokens expire just under 24 hours from generation.
A new token should be requested when the previous expires. A client should not generate a new token with every request to our API.
Get your API credentials
To begin using the Epsilon Retail Media Partner APIs, you need the following information. If you're unsure about any of the details, contact your Support or raise a ticket to get assistance.
- Your user key for authentication.
- The base URL for making API calls.
Retrieve your User key
- Log into your Epsilon Retail Media team account.
- Choose a team.
- From the profile dropdown, select User settings.
- Navigate to the User key tab.
- Click Show to reveal your API key.
Use this key to authenticate your API requests. Epsilon Retail Media uses user key-based authentication. Exchange your user key for a time-limited access token to authorize API requests. For more information, see Authentication requests.
Get your base URL
Contact your Support to obtain the correct base URL for your environment. Example endpoint:
https://campaign.<env>.citrusad.com/v3/campaigns
Once you have your user key, you can authenticate and begin making the API calls to:
- View and manage your advertising campaigns.
- Manage your advertising budgets and spending.
- Manage your team and user details.
Set up the environment
Epsilon Retail Media provides two distinct environments for each retailer: Production and Sandbox. Both environments are created by default when a retailer is onboarded.
Sandbox environment
Sandbox access is typically provided only to retailers and aggregators. If you’re unsure about your eligibility, contact Support.
Use this safe environment to test your integration before going live. Retailers must use this environment to validate API calls, test catalog uploads, simulate campaign creation, and ensure end-to-end functionality before going live. Use the sandbox for all development, testing, and QA activities. Each retailer has a unique sandbox URL, typically in the format:
https://<retailer>-sandbox.citrusad.com
The sandbox environment includes:
Production environment
Switch to production only after successful validation in sandbox. The production environment is used for live campaigns and real-time ad delivery. It supports full-scale operations including catalog updates, order syncing, and ad performance tracking. The production URL follows this format:
https://<namespace>.citrusad.com
Ensure that all data (catalogs, products, orders) is accurate and complete before using this environment.
Always confirm the correct environment before making API calls, especially when using credentials and base URLs. The base URL may not always match the namespace, depending on the retailer’s integration setup.
Partner API endpoints
Epsilon Retail Media API offers a set of core features grouped into functional categories, each supported by dedicated endpoints. The table below summarizes the key partner-facing APIs, their purpose, and the HTTP methods used.
Campaign Management
What is a Sponsored Product Ad?
Sponsored Product Ads (SPA) are ads placed in product grids on the retailer site, typically found on search and category pages as well as PDP and homepage, layered in amongst organic listings.
What is a Banner X Ad?
Banner X ads are fully responsive ad units that grow and change with the user's viewport. They are comprised of numerous creative elements from hero and background images to headline text and call-to-action buttons.
What is a Banner Ad?
A standard Banner is a static image with a click-thru URL behind it.
Product Campaign
| Endpoint | Description | Method |
|---|---|---|
| Create a product campaign | Creates a new product campaign using the details provided in the request body. | POST |
| Retrieve list of all product campaigns | Retrieves a list of all product campaigns based on the provided parameters. | GET |
| Update a product campaign | Updates an existing product campaign using the campaign ID | PATCH |
| Get product campaign by ID | Retrieves product campaign details for the specified campaign ID. | GET |
| Change approval state of a product campaign | Updates the approval state of a specified product campaign. | POST |
| Check booking feasibility for fixed tenancy campaigns | Checks if booking is feasible for fixed tenancy campaigns. | POST |
Banner X Campaign
| Endpoint | Description | Method |
|---|---|---|
| Create a Banner X campaign | Creates a new banner X campaign using the details provided in the request body. | POST |
| Get Banner X campaign details | Retrieves banner X campaign details for the specified campaign ID. | GET |
| Update Banner X campaign | Updates an existing Banner X campaign by providing the campaign ID and the updated campaign data in the request body. | PATCH |
| Update Banner X campaign approval state | Updates the approval state of a specified banner X campaign. | POST |
| Retrieve list of all Banner X campaigns | Retrieves a list of banner X campaigns based on specified filters and parameters, including campaign name, placement ID, team ID, approval state, and more. | GET |
Banner Campaign
| Endpoint | Description | Method |
|---|---|---|
| Create a banner campaign | Creates a new banner campaign using the details provided in the request body. | POST |
| Get banner campaign details | Retrieves banner campaign details for the specified campaign ID. | GET |
| Update banner campaign | Updates an existing banner campaign using the campaign ID. | PATCH |
| Update banner campaign approval state | Updates the approval state of a specified banner campaign | POST |
Campaign Files
| Endpoint | Description | Method |
|---|---|---|
| Upload a campaign file | Uploads different types of campaign files | POST |
| Retrieve campaign file URL | Retrieves the URL of a campaign file using the specified file ID and file type. | POST |
Content Standard
| Endpoint | Description | Method |
|---|---|---|
| Get Banner X content standard details | Retrieves Banner X content standard details for the specified content standard ID. | GET |
| Retrieve list content standards for Banner X campaigns | Retrieves the list of content standards for Banner X campaigns based on the specified parameters, such as namespace, name, and content standard ID. | GET |
| Get banner content standard details | Retrieves Banner content standard details for the specified content standard ID. | GET |
| Retrieve list content standards for banner campaigns | Retrieves the list of content standards for banner campaigns based on the specified parameters, such as namespace, name, and content standard ID. | GET |
Campaign
| Endpoint | Description | Method |
|---|---|---|
| Retrieve list of all campaigns | Retrieves a list of campaigns based on specified filters and parameters, including campaign name, campaign type, placement ID, team ID, approval state, and more. | POST |
| Retrieve campaign history | Retrieves a campaign's history using its campaign ID. | GET |
| Retrieve minimum bid details for keywords | Retrieves individual minimum bid details and the overall campaign minimum bid for an array of specified keywords in Search and Category & Search placement type campaigns. | POST |
| Retrieve minimum bid details for category | Retrieves individual minimum bid details and the overall campaign minimum bid for category placement type campaigns. | POST |
Creative Asset Management
What is a Creative Asset?
Creative assets are images used in Banner and Banner X campaigns. These assets must meet specific technical requirements to ensure proper display and performance.
Upload Guidelines:
- File size < 4 MB
- File types: PNG, JPEG, JPG, GIF, SVG, and PDF
- One file at a time
- Team ID, Slot ID and Content Standard ID are mandatory
- Provide a complete absolute path to the file
Creative asset uploads are handled through the Campaign File endpoints listed in the Campaign Management section above.
Content Standard Management
What is a Content Standard?
Content standards are guidelines and technical parameters that dictate how a Banner or Banner X ad should be displayed within a designated space on a website or digital platform. Standards include parameters such as dimensions and size, file format and sizes, resolution and quality, positioning and alignment, content restrictions and interactivity.
Team & User Management
What is a Team?
A team is a collection of users and is classified as either a supplier (advertiser) or a retailer team. Supplier teams usually create campaigns, while retailers review campaigns and perform administrative tasks. A user in the system can belong to multiple teams or just one. Typically, a team will have users, campaigns, and wallets associated with it.
Team
| Endpoint | Description | Method |
|---|---|---|
| Create team | Creates a new team. | POST |
| Update a team | Updates the details of a team specified by the team_id. | PATCH |
| List all teams | Retrieves a list of teams by providing the parameters such as, name, namespace_id, and seller_id. | GET |
| Get team for specified ID | Retrieves detailed information about a specific team, including its members. | GET |
| Join a team with invitation token | Enables users to join a team using a valid and unexpired invitation token. | POST |
User
| Endpoint | Description | Method |
|---|---|---|
| Invite a user to the team | Sends an invitation to a user to join a specified team. | POST |
| Retrieve user detail using user ID | Retrieves the details of the user currently logged into the Epsilon Retail Media platform. | GET |
| Retrieve user details | Retrieves user details based on the provided team ID. | GET |
| Update current user detail | Modifies the details of the currently logged in user on the Epsilon Retail Media platform. | PATCH |
| Modify user permission | Updates a user's permissions by providing both user ID and team ID. | PATCH |
| Upload a file | Uploads logos for user profiles and teams. | POST |
| Retrieve file URL | Retrieves the URL for a team or user logo using the specified file ID. | POST |
| Remove a user | Removes a user from the team. | DELETE |
Billing & Wallet Management
What is a Wallet?
A wallet stores an advertiser's funds for the purpose of making payments (e.g. paying for realized ads).
Wallet
| Endpoint | Description | Method |
|---|---|---|
| Create a wallet | Creates a wallet within a specified namespace and associates it with a team using the team ID. | POST |
| Update a wallet | Updates a wallet within a specified namespace and teamId. | PATCH |
| Retrieve wallet by ID | Retrieves the details of a specific wallet using its unique identifier, {id}. | GET |
| List all wallets | Retrieves a list of wallets based on specified filters and parameters, including team ID, wallet name, wallet ID, external ID, and more. | GET |
| Get the balance of a specific wallet | Retrieves the current balance of a specified wallet. | GET |
| Manage funds to a specific wallet | Manages fund operations for a specific wallet. | POST |
Spend
| Endpoint | Description | Method |
|---|---|---|
| Retrieve campaign spend details | Calculates the remaining budget for specific campaigns based on their available balance and spending limits. | POST |
Bulk Operation
Campaign
| Endpoint | Description | Method |
|---|---|---|
| Create campaigns in bulk | Creates multiple campaigns simultaneously (up to 1,000) based on campaign type. | POST |
| Update campaigns in bulk | Updates campaigns within a specified namespace. | PATCH |
| Update campaign approval state | Approves or rejects campaigns within a specified namespace. | POST |
| Retrieve bulk operation status | Retrieves the status and details of a bulk campaign operation using the bulk operation ID. | GET |
Wallet
| Endpoint | Description | Method |
|---|---|---|
| Create wallets in bulk | Create multiple wallets at once within your organization (up to 1,000). | POST |
| Retrieve bulk wallet operation status | Retrieves the status of a bulk wallet operation using its bulk ID. | GET |
| Update wallets in bulk | Updates multiple wallets simultaneously. | PATCH |
Team
| Endpoint | Description | Method |
|---|---|---|
| Create teams in bulk | Creates bulk team for an organization. | POST |
| Update teams in bulk | Updates multiple teams simultaneously. | PATCH |
| Retrieve bulk team operation status | Retrieves the status of a bulk team operation using its bulk ID. | GET |
Suggested Search Term
What are Suggested Search Terms?
Suggested search terms are a collection of terms provided via a file from the retailer associating products to specific terms that are presented to the user when creating a campaign on the search terms step. For more information, see Suggested Search Terms.
| Endpoint | Description | Method |
|---|---|---|
| Lists all suggested search terms | Retrieves suggested search terms for catalog targeting suggested search terms based on specified parameters like catalog ID, product code, and more. | GET |
Best Practices
Follow these best practices to ensure a smooth, efficient, and reliable integration with the Epsilon Retail Media Partner APIs:
- Always test in sandbox before production deployment.
- Use bulk endpoints for multiple operations.
- Check for specific data issues in error responses.
- Use compressed files for faster data uploads.
- Refresh access tokens only when expired.
- Validate required fields before submitting requests.
Error Handling
Our Partner APIs return structured JSON error responses to support robust exception handling.
- HTTP Status Code: Standard error codes (400, 401, 403, 500, etc.)
- Error Code: Specific error identifier.
- Message: Human-readable error description.
- Field Violations: Specific field validation errors for data input issues.
For detailed error handling information, see Error handling.
Support and Resources
| Resource | Description |
|---|---|
| Frequently asked questions | Common questions and answers related to API usage and integration. |
| Release notes | Summary of recent updates or changes to the API. |
| Glossary | Definitions of key terms used across the API documentation. |