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 backend-driven path. The Web SDK can also request and render Sponsored Ads for you — see Render Sponsored Ads with the Web SDK, or Serving Sponsored Ads to compare the two.

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 });