Epsilon
Epsilon Retail Media Integration API

The core Epsilon Retail Media (CitrusAd) REST API. Retailers use it to sync product catalogs, catalog products, customers and order data into the platform, and to request product ads, static banner ads and Banner X responsive ads for search, category and cross-sell placements. Requests are JSON over HTTPS authenticated with an HTTP Basic API key; the /ads endpoints additionally support OAuth 2.0 client-credentials bearer tokens. Ad-generation endpoints are served from regional hosts on *.rmn.dotomi.com; the data-sync endpoints are served from a per-tenant integration host on citrusad.com.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.1.0",
  "info": {
    "title": "Epsilon Retail Media Integration API",
    "version": "1",
    "x-source": "https://developers.citrusad.com/integration/reference/"
  },
  "servers": [
    {
      "url": "https://integration-BASE-URL.citrusad.com/v1/"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "x-bearer-format": "basic",
        "x-default": "YOUR_API_KEY"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/ads/generate": {
      "post": {
        "summary": "Generate product and banner ads",
        "description": "",
        "operationId": "generate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "catalogId",
                  "placement",
                  "maxNumberOfAds"
                ],
                "properties": {
                  "catalogId": {
                    "type": "string",
                    "description": "The catalogId you are requesting ads for. Typically a single identifier for a retailer."
                  },
                  "placement": {
                    "type": "string",
                    "description": "The placement you are requesting ads for."
                  },
                  "customerId": {
                    "type": "string",
                    "description": "Your unique customerId. Optional."
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting."
                  },
                  "searchTerm": {
                    "type": "string",
                    "description": "Used for search placements. The exact search term entered by the customer on your site."
                  },
                  "targetedProductGtin": {
                    "type": "string",
                    "description": "Used for cross-sell placements. The product code that is being advertised against"
                  },
                  "maxNumberOfAds": {
                    "type": "integer",
                    "description": "The maximum number of product ads to receive.",
                    "format": "int32"
                  },
                  "contentStandardId": {
                    "type": "string",
                    "description": "The banner contentStandardId. Required for banners."
                  },
                  "bannerSlotIds": {
                    "type": "array",
                    "description": "The banner slots ads are required. Will be superseded by bannerSlots array object.",
                    "items": {
                      "type": "string"
                    }
                  },
                  "productFilters": {
                    "type": "string",
                    "description": "An array or arrays are required depending on your ad generation filtering. Used in category placements or any other placement to further define business rules. Not currently compatible with cross-sell or upsell placements.",
                    "default": "[     [       \"category:Frozen\"     ],     [\"Location:Brisbane Central\"]]",
                    "format": "json"
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "filtermode": {
                          "type": "string",
                          "description": "Defines the ad generation filtering mode.",
                          "default": "AndOr"
                        },
                        "cached": {
                          "type": "boolean",
                          "description": "Defines if the retailer expects to cache the adId",
                          "default": false
                        },
                        "includeAdvertiserInfo": {
                          "type": "boolean",
                          "description": "Defines if the retailer requires advertiser information to comply with the EU's Digital Services Act",
                          "default": true
                        }
                      },
                      "type": "object"
                    }
                  },
                  "bannerSlots": {
                    "type": "array",
                    "description": "The banner slots that are requested. Specifying maxNumberOfAds for the banner allows you to retrieve multiple of the same banner slot.",
                    "items": {
                      "properties": {
                        "slotId": {
                          "type": "string",
                          "description": "The bannerSlotId ads are required for."
                        },
                        "maxNumberOfAds": {
                          "type": "integer",
                          "description": "The maximum number of product ads to receive.",
                          "format": "int32"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "audience": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "segmentIds": {
                          "type": "array",
                          "description": "The list of segment IDs that the customer can access.",
                          "default": [],
                          "items": {
                            "type": "string"
                          }
                        },
                        "sourceId": {
                          "type": "string",
                          "description": "The agreed ID of the source between Epsilon and yourself. Used when multiple sources are used for segments. Not required if only syncing from one source.",
                          "default": "retailer-cdp-1"
                        }
                      },
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"ads\": [\n        {\n            \"id\": \"string\",\n            \"gtin\": \"string\",\n            \"discount\": {\n                \"amount\": \"number\",\n                \"minPrice\": \"number\",\n                \"maxPerCustomer\": \"integer\"\n            },\n            \"expiry\": \"string\",\n            \"position\": \"integer\",\n          \t\"metadata\": {\n        \t\t\t\"advertiserInfo\": {\n       \t\t\t\t\t\"advertiser\": \"string\",\n          \t\t\t\"onBehalfOf\": \"string\",\n      \t\t\t},\n     {\n            \"id\": \"string\",\n            \"gtin\": \"string\",\n            \"discount\": {\n                \"amount\": \"number\",\n                \"minPrice\": \"number\",\n                \"maxPerCustomer\": \"integer\"\n            },\n            \"expiry\": \"string\",\n            \"position\": \"integer\"\n          \t\"metadata\": {\n        \t\t\t\"advertiserInfo\": {\n       \t\t\t\t\t\"advertiser\": \"string\",\n          \t\t\t\"onBehalfOf\": \"string\",\n        },\n       {\n            \"id\": \"string\",\n            \"gtin\": \"string\",\n            \"discount\": {\n                \"amount\": \"number\",\n                \"minPrice\": \"number\",\n                \"maxPerCustomer\": \"integer\"\n            },\n            \"expiry\": \"string\",\n            \"position\": \"integer\"\n          \t\"metadata\": {\n        \t\t\t\"advertiserInfo\": {\n       \t\t\t\t\t\"advertiser\": \"string\",\n          \t\t\t\"onBehalfOf\": \"string\",         \n        }\n    ],\n    \"banners\": [\n        {\n            \"id\": \"string\",\n            \"contentStandardId\": \"string\",\n            \"slotId\": \"string\",\n            \"imageUrl\": \"string\",\n            \"linkUrl\": \"string\",\n            \"altText\": \"string\",\n            \"text\": \"\",\n            \"gtins\": [\n                \"string\",\n                \"string\"\n            ],\n            \"expiry\": \"2022-03-10T05:53:14.653320236Z\",\n            \"tags\": {}\n        }\n    ],\n      \"products\": [],  \n  \"metadata\": []\n\n}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "403": {
            "description": "403",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "429": {
            "description": "429",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "500": {
            "description": "500",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "502": {
            "description": "502",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "503": {
            "description": "503",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "504": {
            "description": "504",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/ads/bannerx": {
      "post": {
        "summary": "Generate banner X ads",
        "description": "",
        "operationId": "bannerx",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "catalogId",
                  "placement"
                ],
                "properties": {
                  "catalogId": {
                    "type": "string",
                    "description": "The catalogId you are requesting ads for. Typically a single identifier for a retailer."
                  },
                  "placement": {
                    "type": "string",
                    "description": "The placement you are requesting ads for."
                  },
                  "customerId": {
                    "type": "string",
                    "description": "Your unique customerId. Optional."
                  },
                  "sessionId": {
                    "type": "string",
                    "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting."
                  },
                  "searchTerm": {
                    "type": "string",
                    "description": "Used for search placements. The exact search term entered by the customer on your site."
                  },
                  "contentStandardId": {
                    "type": "string",
                    "description": "The banner contentStandardId. Required for banners."
                  },
                  "bannerSlotIds": {
                    "type": "array",
                    "description": "The banner slots ads are required for.",
                    "items": {
                      "properties": {
                        "slotId": {
                          "type": "string",
                          "description": "The bannerSlotId ads are required for."
                        },
                        "maxNumberOfAds": {
                          "type": "integer",
                          "description": "The maximum number of product ads to receive.",
                          "format": "int32"
                        }
                      },
                      "type": "object"
                    }
                  },
                  "productFilters": {
                    "type": "string",
                    "description": "An array or arrays are required depending on your ad generation filtering. Used in category placements or any other placement to further define business rules. Not currently compatible with cross-sell or upsell placements.",
                    "default": "[     [       \"category:Frozen\"     ],     [\"Location:Brisbane Central\"]]",
                    "format": "json"
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "filtermode": {
                          "type": "string",
                          "description": "Defines the ad generation filtering mode.",
                          "default": "AndOr"
                        },
                        "cached": {
                          "type": "boolean",
                          "description": "Defines if the retailer expects to cache the adId",
                          "default": false
                        },
                        "includeAdvertiserInfo": {
                          "type": "boolean",
                          "description": "Defines if the retailer requires advertiser information to comply with the EU's Digital Services Act",
                          "default": true
                        }
                      },
                      "type": "object"
                    }
                  },
                  "audience": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "segmentIds": {
                          "type": "array",
                          "description": "The list of segment IDs that the customer can access.",
                          "default": [],
                          "items": {
                            "type": "string"
                          }
                        },
                        "sourceId": {
                          "type": "string",
                          "description": "The agreed ID of the source between Epsilon and yourself. Used when multiple sources are used for segments. Not required if only syncing from one source.",
                          "default": "retailer-cdp-1"
                        }
                      },
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"ads\": [\n        {\n            \"contentStandardId\": \"string\",\n            \"slotId\": \"string\",\n            \"banners\": [\n                {\n                    \"citrusAdId\": \"string\",\n                    \"citrusCampaignName\": \"string\",\n                    \"citrusContentStandardId\": \"string\",\n                    \"citrusSlotId\": \"string\",\n                    \"citrusExpiry\": \"string\",\n                    \"headingText\": \"string\",\n                    \"bannerText\": \"string\",\n                    \"bannerTextColour\": \"string\",\n                    \"ctaFlag\": boolean,\n                    \"ctaText\": \"string\",\n                    \"ctaTextAccessibility\": \"string\",\n                    \"ctaLink\": \"string\",\n                    \"backgroundColour\": \"string\",\n                    \"backgroundImage\": \"string\",\n                    \"backgroundImagePosition\": \"string\",\n                    \"heroImage\": \"string\",\n                    \"heroImageAltText\": \"string\",\n                    \"secondaryHeroImage\": \"string\",\n                    \"secondaryHeroImageAltText\": \"string\",\n                    \"tags\": {},\n                    \"gtins\": [\n                        \"string\",\n                        \"string\"\n                    ],\n                    \"position\": integer,\n                  \t\"metadata\": {\n        \t\t\t\t\t\t\t\"advertiserInfo\": {\n          \t\t\t\t\t\t\t\"advertiser\": \"string\",\n          \t\t\t\t\t\t\t\"onBehalfOf\": \"string\"\n                      }\n                }\n            ]\n        }\n    ],  \n  \"metadata\": []\n}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "403": {
            "description": "403",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "429": {
            "description": "429",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "500": {
            "description": "500",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "502": {
            "description": "502",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "503": {
            "description": "503",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "504": {
            "description": "504",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    },
    "/orders": {
      "post": {
        "summary": "Report an order",
        "description": "",
        "operationId": "report-an-order",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orders": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The order ID in the retailer's site. If not provided it is generated by CitrusAd in the response."
                        },
                        "sessionId": {
                          "type": "string",
                          "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting."
                        },
                        "orderDate": {
                          "type": "string",
                          "description": "This is the date or the date and time of the order. This must be in the format of ISO-8601 RFC 3339 standard and must be a precise, full timestamp, e.g. 2019-03-14T15:06:17+10:00",
                          "format": "date-time"
                        },
                        "orderItems": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "gtin": {
                                "type": "string",
                                "description": "The product code of the purchased product."
                              },
                              "quantity": {
                                "type": "integer",
                                "description": "The quantity (units) of the product purchased.",
                                "format": "int32"
                              },
                              "regularUnitPrice": {
                                "type": "string",
                                "description": "This is regular unit price of the product in the order.  If provided, it MUST be a number."
                              },
                              "totalOrderItemPriceAfterDiscounts": {
                                "type": "string",
                                "description": "This is the total price of the products with discounts. It MUST be a number, e.g. if an order item contains 3 items with a price of 2.00, the value will be 6."
                              },
                              "sellerId": {
                                "type": "string",
                                "description": "The unique Id of the seller. Only required if onboarding marketplace sellers. Can be left blank for non marketplace products.   There are additional requirements to integrate seller_ids, please refer to [Marketplace sellerId](https://developers.citrusad.com/integration/reference/marketplace-sellerid) for more information."
                              }
                            },
                            "required": [
                              "gtin",
                              "quantity",
                              "totalOrderItemPriceAfterDiscounts"
                            ],
                            "type": "object"
                          }
                        }
                      },
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"orders\": [\n        {\n            \"adIds\": \"string\",\n            \"teamId\": \"string\",\n            \"customerId\": \"string\",\n            \"sessionId\": \"string\",\n            \"id\": \"string\",\n            \"orderItems\": [\n                {\n                    \"regularUnitPrice\": \"number\",\n                    \"citrusDiscountAmount\": \"number\",\n                    \"gtin\": \"string\",\n                    \"adId\": \"string\".\n                    \"quantity\": \"number\",\n                    \"substitutedFor\": \"string\",\n                    \"totalOrderItemPriceAfterDiscounts\": \"number\"\n                }\n            ],\n            \"orderDate\": \"string\"\n        }\n    ]\n}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"additionalInfo\": [\n        {\n            \"code\": \"string\",\n            \"message\": \"string\"\n        }\n    ],\n    \"message\": \"string\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "additionalInfo": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "code": {
                            "type": "string",
                            "example": "string"
                          },
                          "message": {
                            "type": "string",
                            "example": "string"
                          }
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "example": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "401",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "403": {
            "description": "403",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "429": {
            "description": "429",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "500": {
            "description": "500",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "502": {
            "description": "502",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "503": {
            "description": "503",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          },
          "504": {
            "description": "504",
            "content": {
              "text/plain": {
                "examples": {
                  "Result": {
                    "value": ""
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      },
      "get": {
        "summary": "Retrieve a list of orders",
        "description": "",
        "operationId": "retrieve-a-list-of-orders",
        "parameters": [
          {
            "name": "teamId",
            "in": "query",
            "description": "If a teamId is not provided, then the teamId will fall back onto the teamId provided by the authentication.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "skip",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "orderIds",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orders": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The order ID in the retailer's site. If not provided it is generated by CitrusAd in the response."
                        },
                        "sessionId": {
                          "type": "string",
                          "description": "Unique sessionId used for attribution. Required to be consistent between a user's session and order reporting."
                        },
                        "orderDate": {
                          "type": "string",
                          "description": "This is the date or the date and time of the order. This must be in the format of ISO-8601 RFC 3339 standard and must be a precise, full timestamp, e.g. 2019-03-14T15:06:17+10:00",
                          "format": "date-time"
                        },
                        "orderItems": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "gtin": {
                                "type": "string",
                                "description": "The product code of the purchased product."
                              },
                              "quantity": {
                                "type": "integer",
                                "description": "The quantity (units) of the product purchased.",
                                "format": "int32"
                              },
                              "regularUnitPrice": {
                                "type": "string",
                                "description": "This is regular unit price of the product in the order.  If provided, it MUST be a number."
                              },
                              "totalOrderItemPriceAfterDiscounts": {
                                "type": "string",
                                "description": "This is the total price of the products with discounts. It MUST be a number, e.g. if an order item contains 3 items with a price of 2.00, the 

# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/epsilon/refs/heads/main/openapi/epsilon-retail-media-integration-openapi.json
Epsilon Retail Media Integration API

Documentation

Specifications

Other Resources

OpenAPI Specification
