For the complete documentation index, see llms.txt. This page is also available as Markdown.

API overview

Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view this page in the new Integration APIs space of our documentation.

How does Epsilon Retail Media work?

The API is organised around REST. The API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. The API uses built-in HTTP features including HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

Authentication to the API is managed through the use of API keys. API keys are used during communication between your backend and the API.

The Integration API supports the upload of products, catalogs, customers, and order data, which is used to generate ads. You can use the Integration API to request ads and report on interactions with those ads.

Integration endpoints

Epsilon Retail Media uses various endpoints to sync data and generate ads. A brief summary is provided below:

Endpoint
Use
Description

catalogs

Used to create catalogs via API. For single catalog namespaces, this is something your Technical Account Manager can organise for you.

catalog-products

Used to create and update product data within a catalog.

customers

Used to create and update customer data within a catalog.

orders

Used to send order data.

/resource/

Used to report clicks and impressions, as well as orders if reporting via front-end.

/ads/generate

Generating ads

Used to generate product ads and banner ads.

/ads/bannerx

Generating ads

Used to generate banner x ads.

You don’t need to use endpoints for catalog, product, customer, and order syncing. Epsilon Retail Media supports syncing data via file, which may be suitable for your requirements.

Content type & payload

The data payload is in JSON format. The Content-Type for these endpoints is application/json, which should be passed as a header in your requests as follows:

Authenticating requests

Basic authentication

All integration resources use basic authentication which should be passed as a header with your API key as follows:

Your API Key can be accessed in the Integration Settings section of the retailer team. You will only need the secret API key.

OAuth2.0 authentication

Epsilon Retail Media's ad generation endpoint is additionally compatible with OAuth2.0. Review OAuth 2.0 Authentication for more information.

Base URLs

Epsilon Retail Media uses different base URLs for staging and production environments.

To receive your staging base URL, please contact Epsilon Retail Media. Once your integration is in progress, we will provide you with production base URLs.