Skip to main content
retail media

Sponsored Ads

active
Audience: developerUpdated 2026-07-29

Sponsored Ads promote a seller's or advertiser's offering blended into the shopping experience — on product, category, search, and listing pages — rather than as a standalone display unit.

Why Sponsored Ads​

Your store already has an audience with purchase intent — visitors browsing products, searching, and comparing categories. Sponsored Ads lets sellers and advertisers promote their products and brands on those high-intent surfaces (Search, Category, and Product Detail pages), increasing their visibility right where shoppers are already deciding what to buy.

The defining idea is that Sponsored Ads are contextual, not behavioral: they target based on where the user is and what they're browsing right now, not who the user is or what traits they have. The page context is the signal.

Before you start, complete the shared Retail Media setup: define your media property, your ad slots (choose the Sponsored Ads category), get your connection, credentials & host URLs, and — crucially — sync your catalog. Sponsored Ads promote real products, so the catalog is required.

Subtypes​

SubtypePromotes
ProductA set of specific products
BrandA brand: its logo plus some of that brand's products
DisplayA banner whose link takes the user to a product, category, brand, or seller page

Contexts​

Every Sponsored Ads slot is tied to one or more page Contexts. The Context decides what the runtime request must carry about what the user is browsing — see the full table in Ad Slots & Formats. Product Listing Page is the one exception: it fills from promotion targeting, and productId / categoryId / keyword are ignored even if sent.

Setup recap​

Sponsored Ads reuse the shared foundation. Same as Display Ads, you:

  1. Define the media property first — Define the media property.
  2. Define slots per media — Define ad slots, choosing the Sponsored Ads category, a subtype (Product / Brand / Display), a placementCount, and one or more Contexts.

What's extra for Sponsored Ads is the catalog — the platform can only promote products, brands, and sellers it knows about. See Catalog API.

Serving Sponsored Ads​

Sponsored Ads are served through the API: your backend calls the Sponsored Ads API, you render the returned ads inside your own components, and you track them by bidId. The Web SDK still runs on the page — for identity and event tracking, not rendering.

Guide: Request and render Sponsored Ads.

This fits marketplaces well anyway. The product, search, and category UI changes frequently, and pulling ads from your backend keeps ad serving decoupled from that UI churn — the inverse of Display Ads, where SDK rendering is the recommended path.

Requesting sponsored ads (at a glance)​

Endpoint: POST {rtbPath}/api/rtb/sponsoredAd

You provide the page context — at least one of productId, categoryId, or keyword (priority in that order) — plus adSlotIds, mediaSource, and user. The response's ads[] carry a type of BRAND, PRODUCT, DISPLAY_BANNER, or DISPLAY_NATIVE, each with a bidId for tracking. See the Sponsored Ads API reference.

Track impressions & clicks​

This step is required, exactly as it is for Display Ads — and uses the same shared flow for both families. Once an ad is rendered you must report its impression and click events, plus load, keyed by the bidId on each returned item.

Because you render Sponsored Ads yourself, you also fire these events yourself — preferably through the Web SDK on the page. (Only SDK-rendered Display Ads get automatic tracking.)

Both families route to the single shared page: Track ad impressions and clicks, with attribution via Web SDK reference → Identity.

Next steps​

Last updated on