Skip to main content
retail media

Request and render Sponsored Ads

active
Audience: developerUpdated 2026-07-29

Your backend calls the Sponsored Ads API, you render the returned ads inside your own components, and track them by bidId. Run the Web SDK on the page too — for identity and tracking, not rendering.

This is the only serving path for Sponsored Ads: the Web SDK renders Display Ads only, so there is no SDK equivalent of this flow — see Sponsored Ads → Serving Sponsored Ads.

Every field of the request and response is specified in the Sponsored Ads API reference.

Step 1 — Read identity​

Binoban.user().anonymousId(); // → put in user.id
Binoban.user().id();          // → put in user.userId

See Web SDK reference → Identity for the full reference.

Step 2 — Request sponsored ads​

curl --location '{rtbPath}/api/rtb/sponsoredAd' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "productId": "shoe123",
    "categoryId": "cat456",
    "keyword": "sneakers",
    "adSlotIds": [21],
    "mediaSource": { "type": "SITE" },
    "user": { "userId": "phoneNumber or userId", "id": "anonymousId" },
    "timeout": 200
  }'

rtbPath is the host URL from your connection; no authentication is required on this endpoint.

Send only the context field(s) that match the slot's Context — a Product Listing Page slot sends none of them.

Step 3 — Render by type​

typeCarriesYou render
PRODUCTproducts[] (catalog references)Your product cards, from your own catalog
BRANDbrand + products[]Brand logo + that brand's product cards
DISPLAY_BANNERbanner, width, height, landing_url, bidIdThe banner image, linking to landing_url
DISPLAY_NATIVEnatives[] (assets)Native assets in your own template

For PRODUCT and BRAND, the response returns catalog references, not ready-made creatives — look each products[].id up in your own catalog and render your own card.

Note the destination field here is landing_url (snake_case), not the Ad Request API's landingUrl / targetUrl — see landing_url vs landingUrl.

Hold onto every bidId — each tracking call needs it, along with the item's index in the response.

Step 4 — Track impression, click, and load​

Report events keyed by bidId, preferably through the Web SDK on the page (see Track ad impressions and clicks):

Binoban.track("ads_load",       { bid_id: "550e8400-e29b-41d4-a716-446655440003", index: 0 });
Binoban.track("ads_impression", { bid_id: "550e8400-e29b-41d4-a716-446655440003", index: 0 });
Binoban.track("ads_click",      { bid_id: "550e8400-e29b-41d4-a716-446655440003", index: 0 });
Last updated on