> 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/brand-pages/brand-page-retailer-integration-guide/brand-page-apis.md). # Brand Page APIs ## URL Routing When a user navigates to a brand page URL, your application extracts the `urlSlug` from the path and sends it to the ad‑serving API. URL structure: `` | Segment | Source | Example | | ------------- | ------------------------------------------------- | ------------------ | | `your-domain` | Your site | `www.retailer.com` | | `prefix` | Configured during onboarding (e.g. brands, pages) | `brands` | | `urlSlug` | Extracted at runtime from the URL path | `adidas` | **Example** When a user visits: `` 1. Your application matches the `/brands/*` route. 2. Extracts `adidas`as the urlSlug. 3. Calls `POST /ads/v3/brand-pages` on your assigned ads host with `"urlSlug": "adidas"` and your `catalogId`. 4. Renders the returned content modules on the page. ### Slug Validation Rules Brands create slugs following these constraints: * **Characters:** Lowercase letters (a–z), numbers (0–9), hyphens (-), and underscores (\_). * **Length:** Minimum 3 characters, maximum 100 characters. * **Uniqueness:** Must be unique within the retailer’s catalog (`catalogId`). {% hint style="info" %} At this time, slug uniqueness does not consider campaign date ranges. {% endhint %} * **Immutability:** Cannot be changed after the brand page campaign is live. * **Format:** No leading or trailing hyphens (for example, `-adidas`or `adidas-` are not allowed). ## Caching * Do not cache responses from the ad‑serving API. Always send requests directly to the Epsilon API to ensure: * The correct brand page campaign is served (campaigns may be paused, updated, or swapped). * Tracking URLs include fresh, per‑request identifiers for accurate attribution. * Impression counts remain accurate and are not affected by stale cached responses. **SEO Consideration**: Retailers may choose to allow Brand Pages to be indexed by search engines. Indexing brand page content can improve organic search visibility, as all text on the page is discoverable by search engines. ## Reverse Proxy Setup ### Why You Need a Reverse Proxy **The Problem**: Ad blockers and privacy tools often block tracking requests sent directly to advertising domains. **The Solution**: Route all tracking requests through your own domain so they appear as first‑party traffic. ```apache ❌ Blocked: user-browser → [third-party-tracking-domain] ✅ Works: user-browser → yoursite.com/[custom-path] → [third-party-tracking-domain] ``` * Replace `[third-party-tracking-domain]` with the actual Epsilon tracking endpoint provided during onboarding. * Replace `[custom-path]` with a neutral, unique path (e.g., `/media-proxy`, `/assets-endpoint`, or any non-advertising term). A reverse proxy is required for C2S (browser) tracking. It does not apply to S2S calls, which must be sent directly to the Epsilon tracking host [(see Tracking – Server-to-Server (S2S](/retail-media-interface/integration/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.md#tracking--servertoserver-s2s))). ### Configuration Your site must host a reverse proxy under a path such as `https://www.retailer.com/{proxyPath}/`. Browser (C2S) tracking requests to your domain on that path are forwarded to your regional tracking host ([see Ad Serving API](#ad-serving-api)). Server-to-server tracking must not use this proxy. **Behavior:** * Accept requests under `/epsilon/` * Forward to `https://[region]-tracking.rmn.dotomi.com/` (see [Ad Serving API](#ad-serving-api) for `[region]`) * Preserve the file-path suffix * Forward required HTTP headers * Enforce HTTPS (TLS 1.2+) ### Required Headers | Header | Description | | -------------------------- | --------------------------------------------- | | `RP-Host` | Your hostname receiving the tracking request. | | `X-Forwarded-For` | Actual client IP address. | | `X-Forwarded-Request-Path` | Proxy prefix path (e.g. /epsilon). | | `Referer` | The page where the pixel fired. | ### Apache Example ```apache LoadModule ssl_module modules/mod_ssl.so LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so SSLProxyEngine on RequestHeader add "X-Forwarded-Request-Path" "/epsilon" RequestHeader add "RP-Host" "%{HTTP_HOST}s" RequestHeader add "Referer" "%{HTTP_REFERER}s" ProxyPass "/epsilon" "https://[region]-tracking.rmn.dotomi.com" ProxyPassReverse "/epsilon" "https://[region]-tracking.rmn.dotomi.com/" ``` ### NGINX Example ```apache server { server_name www.retailer.com; location /epsilon/ { proxy_ssl_server_name on; rewrite ^/epsilon/(.*) /$1 break; proxy_pass https://[region]-tracking.rmn.dotomi.com; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Server $server_name; proxy_set_header RP-Host $host; proxy_set_header X-Forwarded-Request-Path "/epsilon"; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Referer $http_referer; } } ``` ## Ad Serving API Epsilon serves brand pages from RMN hosts on `*.rmn.dotomi.com`. Substitute `[region]` with the segment Epsilon assigns for your deployment. The ads API uses `https://[region]-ads.rmn.dotomi.com`; while tracking endpoints (impression pixels, click redirects, and S2S notification URLs) uses `https://[region]-tracking.rmn.dotomi.com` with the same `[region]` value. In some setups, the base hostnames `ads.rmn.dotomi.com` and `tracking.rmn.dotomi.com` may be used. Epsilon will confirm the appropriate hostnames for your environment. ### Endpoint ``` POST https://[region]-ads.rmn.dotomi.com/ads/v3/brand-pages Content-Type: application/json Authorization: Basic ``` ### Request Payload ``` { "id": "req-adidas-12345", "catalogId": "test-catalog-adidas", "urlSlug": "adidas", "site": { "domain": "www.retailer.com", "page": "https://www.retailer.com/brand/adidas", "ref": "https://www.retailer.com/search?q=shoes" }, "device": { "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...", "ip": "192.168.1.100", "language": "en-US", "devicetype": 2, "os": "macOS", "geo": { "country": "USA", "region": "CA", "city": "San Francisco", "zip": "94105" } }, "user": { "sessionId": "sess-abc123xyz", "customerId": "cust-789012", "dtmId": "dtm-456def" }, "regs": { "gdpr": 1, "consent": "COwJqZAOwJqZAOAAAAENAXCAAAAAAAAAAAAAABpoAIAAAEpgAIAAAg1AAAICAIAAAEA" } } ``` The `regs` values above illustrate the GDPR-applicable traffic:\ `gdpr` is `1`, and `consent`is a **synthetic IAB TCF v2 consent string** (correct shape and charset only). In production environments: * Set `gdpr`from your geo and legal rules. * Pass the **live TC string** from your CMP (for example via `_ _tcfapi` `getTCData`→ `tcString`). For non-GDPR requests, use `"gdpr": 0` and omit `consent`or use `""` `iabConsentString` on tracking events: Every populated tracker slot (`trackers.impression`, `trackers.click`, `trackers.addToCart`) includes `params.iabConsentString`. When you provide `regs.consent` on the request, this value is the literal TC string. When you omitted `regs.consent`, this value is the {TCF} macro placeholder - substitute the current TCF v2 string from your CMP (for example via `__tcfapi getTCData` → `tcString`) at fire time before sending any tracking request. ### Request Field Definitions | Field | Type | Required | Description | | -------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Yes | Unique request identifier (generated by retailer) | | `catalogId` | string | Yes | Retailer's product catalog ID (provided by Epsilon) | | `urlSlug` | string | Yes | Brand page URL slug (e.g. adidas) | | **site** | | | | | `site.domain` | string | Yes | Retailer website domain | | `site.page` | string | No | Full URL where the brand page is rendered | | `site.ref` | string | No | Referrer URL (where the user navigated from) | | **device** | | | | | `device.ua` | string | Yes | User agent string | | `device.ip` | string | No | Client IP address | | `device.language` | string | No | Browser language (e.g. en-US) | | `device.devicetype` | integer | No | 1=mobile, 2=pc, 4=phone, 5=tablet | | `device.os` | string | No | Operating system | | `device.geo.country` | string | No | ISO 3166-1 alpha-3 country code (e.g. USA, GBR) | | `device.geo.region` | string | No | State or region | | `device.geo.city` | string | No | City | | `device.geo.zip` | string | No | Postal/ZIP code | | **user** | | | | | `user.sessionId` | string | No | Retailer session identifier (non-PII) | | `user.customerId` | string | No | Retailer customer identifier (non-PII) | | `user.dtmId` | string | No | Tracking identifier | | **regs** | | | | | `regs.gdpr` | integer | No | `0` = GDPR does not apply, `1` = GDPR applies (per OpenRTB-style signaling) | | `regs.consent` | string | No | IAB TCF **v2** consent string (`tcString` from the CMP). Use only when `gdpr` is `1` and you have a valid string; otherwise omit or`""` | {% hint style="danger" %} **Important** The JSON below is a representative and fairly complete example. Live responses are often sparser for `contentData` modules. Do not generate fixed structures that assume every key shown here is always present for every `contentType` or brand page.\ The `theme` is different: on a successful response, it is always present and uses the nested structure described in the Theme Object section (`colors`and `buttons` fully populated - required hex6 strings for every path; no `nulls` inside `theme`). {% endhint %} ### Response Payload ``` { "realizedAdId": "brandpage_djogXfHSYGZOZnnkzEKunWvdNYEKABIAGgwIwIPjzAYQ3byasAE=", "brandPageTemplateId": "6e9690ef-81d1-4fad-b2ce-749e22cceb10", "catalogId": "test-catalog-adidas", "urlSlug": "adidas", "theme": { "colors": { "background": "#F5F5F5", "text": { "heading": "#1a1a1a", "subheading": "#333333", "body": "#5f6368", "caption": "#9aa0a6", "link": "#1a73e8", "tagline": "#5f6368", "lines": "#e0e0e0" } }, "buttons": { "primary": { "background": "#ff6600", "text": "#FFFFFF" }, "secondary": { "background": "#FFFFFF", "text": "#ff6600" } } }, "trackers": { "impression": { "type": "impression", "params": { "ts": "{TS}", "iabConsentString": "{TCF}" } } }, "trackingTypes": { "impression": ["client.impressionPixelUrls", "server.impressionEvent"], "productClick": ["client.clickRedirect", "client.clickEvent", "server.clickEvent"], "productAddToCart": ["client.addToCartEvent", "server.addToCartEvent"], "link": ["client.clickRedirect", "client.clickEvent", "server.clickEvent"], "interaction": ["client.clickEvent", "server.clickEvent"] }, "trackingTemplates": { "client": { "clickRedirect": "/tracking/v3/click/redirect/brandpage_djog...?catalogId=test-catalog-adidas&...", "clickEvent": "/tracking/v3/event/click/brandpage_djog...?catalogId=test-catalog-adidas&...", "addToCartEvent": "/tracking/v3/event/add-to-cart/brandpage_djog...?catalogId=test-catalog-adidas&...", "impressionPixelUrls": [ "/tracking/v3/impression/pixel/brandpage_djog...?catalogId=test-catalog-adidas&..." ] }, "server": { "clickEvent": "https://[region]-tracking.rmn.dotomi.com/tracking/v3/event/click/brandpage_djog...?...", "addToCartEvent": "https://[region]-tracking.rmn.dotomi.com/tracking/v3/event/add-to-cart/brandpage_djog...?...", "impressionEvent": "https://[region]-tracking.rmn.dotomi.com/tracking/v3/event/impression/brandpage_djog...?..." } }, "contentData": [ { "id": "hero-1", "brandPageModuleTemplateId": "hero-template-1", "contentType": "HERO", "order": 1, "tags": ["header"], "mediaUrl": "https://example.com/images/adidas-hero.jpg", "headline": "Impossible Is Nothing", "subheadline": "Spring Collection", "ctaText": "Explore", "ctaLink": "https://example.com/adidas/explore", "trackers": { "click": { "type": "link", "params": { "modId": "hero-1", "rurl": "https%3A%2F%2Fexample.com%2Fadidas%2Fexplore", "ts": "{TS}", "iabConsentString": "{TCF}" } } } }, { "id": "text-1", "brandPageModuleTemplateId": "text-template-1", "contentType": "TEXT", "order": 2, "text": "Discover the latest Adidas collection featuring innovative designs and sustainable materials." // (No trackers for TEXT module, as it has no interactive elements) } ] } ``` #### Response Field Definitions | Field | Type | Description | | ----------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `realizedAdId` | string | Unique ad identifier for this brand page serve. Used in all tracking template paths. | | `brandPageTemplateId` | string | Template ID used for this brand page | | `catalogId` | string | Retailer catalog ID (echoed from request) | | `urlSlug` | string | Brand page URL slug (echoed from request) | | `theme` | Object |

Always present on success. Page-level styling from the brand: nested colors (background + text roles) and buttons(primary/ secondary, each with backgroundand text). See Theme Object section.
The response body is returned as serialized by the ad server (no intermediate reshaping of theme)

| | `trackers` | object | Page-level tracking container. `trackers.impression` holds the page impression slot: `type: "impression"` and `params` including at least `ts: "`{TS}`"` and `iabConsentString`. | | `trackingTypes` | object | Map of tracking type to applicable template keys. Types: `impression`, `productClick`, `productAddToCart`, `link`, `interaction`. Each value is an array of `client.*/` `server.*` keys from `trackingTemplates`. (see [How to Compose a Tracking URL](/retail-media-interface/integration/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.md#how-to-compose-a-tracking-url)). | | `trackingTemplates.client` | object | **Relative** URL paths and query strings for browser (C2S) tracking - prepend your reverse-proxy base URL (`BASEURL`). | | `trackingTemplates.server` | object | **Absolute** URL templates on the Epsilon tracking host for S2S. | | `contentData[]` | array | Ordered array of content modules to render | | `contentData[].id` | string | Module instance ID | | `contentData[].brandPageModuleTemplateId` | string | Module template ID | | `contentData[].contentType` | string | Module type: HERO, TEXT, FILTER\_MENU, PRODUCT\_GRID, IMAGE, IMAGE\_GALLERY, SPLIT\_LAYOUT | | `contentData[].order` | integer | Rendering order (ascending) | | `contentData[].tags` | array of strings | Optional. Module tags set by the retailer in the template. Omitted entirely when no tags are set - treat missing as "no tags". Also present on nested modules within SPLIT\_LAYOUT. | | `contentData[].trackers` | object | When present, per-node tracking container. `trackers.click` for link/interaction/product click events; `trackers.addToCart` for product add-to-cart (includes {QTY} and {CONVERSION\_VALUE} macros). May be omitted when there is nothing to track. | ### Theme Object Every successful Brand Page API response includes a `theme` object: page-level colors and button styles configured for the brand. Apply these values when rendering (for example, map them to CSS custom properties or your design tokens). The JSON is produced by the ad server and delivered as returned - there is no separate step that rewrites the `theme`. **Color format:** Theme color values follow the platform contract from upstream (campaign/configuration): each value is a `#` followed by six hexadecimal digits (hex6), for example, `#ff6600`. Do not expect other formats (short hex3, eight-digit hex, `rgb()`, `hsl()`, or named colors). The ad server does not revalidate color format at serve time; upstream supplies hex6 for every theme field. #### Structure and semantics * `theme` contains `colors` and `buttons` - both are required whenever `theme` is present. * `colors.background` - page or canvas background (required hex6). * `colors.text` - seven required roles: `heading`, `subheading`, `body`, `caption`, `link`, `tagline`, `lines` (lines/dividers). Each value is a hex6 string. * `buttons.primary` and `buttons.secondary` - each requires `background` and `text` (button fill and label colors), each a hex6 string. * Every path in the field reference table below is required. There are no optional color slots and no `null` values inside `theme`. (Sparse or omitted fields apply elsewhere, for example in `contentData` modules.) * The `theme` is page-level -all modules on the Brand Page share the same theme. #### Field reference All paths in this table are required (non-null hex6 strings). | Path | Description | | ------------------------------------ | ------------------------ | | `theme.colors.background` | Page/canvas background | | `theme.colors.text.heading` | Heading text | | `theme.colors.text.subheading` | Subheading text | | `theme.colors.text.body` | Body/paragraph text | | `theme.colors.text.caption` | Caption/secondary text | | `theme.colors.text.link` | Link text | | `theme.colors.text.tagline` | Tagline text | | `theme.colors.text.lines` | Lines and dividers | | `theme.buttons.primary.background` | Primary CTA button fill | | `theme.buttons.primary.text` | Primary CTA button label | | `theme.buttons.secondary.background` | Secondary button fill | | `theme.buttons.secondary.text` | Secondary button label | **Example - (**`theme`**object only):** ```json "theme": { "colors": { "background": "#F5F5F5", "text": { "heading": "#1a1a1a", "subheading": "#333333", "body": "#5f6368", "caption": "#9aa0a6", "link": "#1a73e8", "tagline": "#5f6368", "lines": "#e0e0e0" } }, "buttons": { "primary": { "background": "#ff6600", "text": "#FFFFFF" }, "secondary": { "background": "#FFFFFF", "text": "#ff6600" } } } ``` #### Per-node `params`(typical keys) | Param | When used | Description | | ------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `modId` | Most interactive nodes | Content module or row identifier. | | `rurl` | `link` / `productClick`when a redirect is needed | URL-encoded destination | | `ts` | Most events | Cache-busting timestamp; substitute `"{TS}"`at fire time. | | `iabConsentString` | All tracker slots | Literal TC string, or {TCF} macro to substitute at fire time | | `productCode` | `productClick` / `productAddToCart` | Product identifier. | | `sellerId` | `productClick` / `productAddToCart` (marketplace) | Seller identifier. | | `qty` | `productAddToCart` | Absolute quantity of this SKU in the cart at the time the event fires (not a delta). Substitute {QTY} macro at fire time | | `conVal` | `productAddToCart` | Absolute monetary value of those items: quantity × unit price, minus any applied discounts. Substitute `{CONVERSION_VALUE}` macro at fire time | #### Template-dependent fields in `contentData` Aside from core discriminators on each module (`id`, `brandPageModuleTemplateId`, `contentType`, `order`), property presence is not uniform across Brand Pages. Prefer feature detection - check each property before use - rather than treating every field in examples as mandatory. The API may represent "no value" in several ways: | Pattern | Meaning | Suggested handling | | --------------- | ------------------------------------ | ---------------------------------------------------------- | | Key omitted | Property absent from the JSON object | Treat as absent; use optional chaining/defaults | | Explicit `null` | Property present with `null` value | Same as omitted, unless your serializer distinguishes them | | Empty string | `""` for text or URL-like fields | Usually hide or skip rendering that slice of UI | #### Examples for Common Module Types **Product Grid:** Each product row includes a `product` object (`catalogId`, `productCode`, `sellerId`), an `order` value, and `trackers` when the row is trackable. Product rows provide both a `click` slot (`type: "productClick"`) and an `addToCart`slot (`type: "productAddToCart"`) when the SKU is attributable. ``` { "product": { "catalogId": "550e8400-e29b-41d4-a716-446655440001", "productCode": "9221200653341", "sellerId": "2ae0aab9-44ce-40a0-b2b9-ae61681ad224" }, "order": 1, "trackers": { "click": { "type": "productClick", "params": { "modId": "grid-1", "productCode": "9221200653341", "sellerId": "2ae0aab9-44ce-40a0-b2b9-ae61681ad224", "rurl": "{RURL}", "ts": "{TS}", "iabConsentString": "{TCF}" } }, "addToCart": { "type": "productAddToCart", "params": { "modId": "grid-1", "productCode": "9221200653341", "sellerId": "2ae0aab9-44ce-40a0-b2b9-ae61681ad224", "rurl": "{RURL}", "ts": "{TS}", "qty": "{QTY}", "conVal": "{CONVERSION_VALUE}", "iabConsentString": "{TCF}" } } } } ``` **Hero:** Headline, subheadline, CTA text and link, image, overlay, and `trackers.click` for the CTA when present. ``` { "contentType": "HERO", "tags": [ "header" ], "mediaUrl": "https://example.com/images/adidas-hero.jpg", "headline": "Impossible Is Nothing", "subheadline": "Spring Collection", "ctaText": "Explore", "ctaLink": "https://example.com/adidas/explore", "trackers": { "click": { "type": "link", "params": { "modId": "hero-1", "rurl": "https%3A%2F%2Fexample.com%2Fadidas%2Fexplore", "ts": "{TS}", "iabConsentString": "{TCF}" } } } } ``` **Image Gallery:** An array of images, each with a URL, alt text, and caption. `trackers.click` for an image only when that image links out. ``` { "contentType": "IMAGE_GALLERY", "galleryImages": [ { "url": "https://example.com/images/recipe-spaghetti-bolognese.jpg", "alt": "Spaghetti Bolognese", "caption": "Spaghetti Bolognese", "trackers": { "click": { "type": "link", "params": { "modId": "gallery-1", "rurl": "https%3A%2F%2Fexample.com%2Frecipes%2Fspaghetti", "ts": "{TS}", "iabConsentString": "{TCF}" } } } } ] } ``` **Text:** Headline and body text, with no `trackers`unless a link is present on a line. ``` { "contentType": "TEXT", "text": "Explore our newest arrivals designed for comfort, style, and performance." } ``` **Image:** Includes an image URL, caption, alt text, optional link and `trackers.click` details when the image is clickable ``` { "contentType": "IMAGE", "imageUrl": "https://example.com/images/model.jpg", "caption": "New arrivals now available", "alt": "Model wearing summer collection", "trackers": { "click": { "type": "link", "params": { "modId": "image-1", "rurl": "https%3A%2F%2Fexample.com%2Fnew-arrivals", "ts": "{TS}", "iabConsentString": "{TCF}" } } ``` --- # 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/brand-pages/brand-page-retailer-integration-guide/brand-page-apis.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.