Shoppable ads
Shoppable ads are display placements that combine brand creative with shoppable item cards. Customers can click the creative or add an advertised item to their cart without leaving the page.
Carrot Ads serves two shoppable formats:
- Shoppable display. A static hero creative with a brand logo, tagline, and a row of item cards.
- Shoppable video. A video creative with a poster image and a row of item cards.
Shoppable video is rolling out progressively. Confirm with your Instacart representative whether your account can request shoppable_video.
When you render either format, include the Sponsored label so customers can identify the placement as an ad. For each image asset, use the asset's alt_text value as the image's alternative text.
Customer experience
Shoppable placements are interleaved with the page's content or results. The response does not specify a display_position. Your storefront determines where to insert each placement within the content feed.
Your storefront can request multiple interleaved placements for a page. Choose insertion points that fit your page layout and customer experience. The number of creatives returned depends on available ad inventory.
The customer sees the brand creative, can play video when the format is shoppable video, and can add items from the item-card row. Selecting the creative can open a brand page. Selecting an item card opens that product.
Placement types
| Requested format | What the API returns | Typical assets |
|---|---|---|
shoppable_display | A shoppable display creative with item-card actions. | hero_image, brand_logo, and tagline copy, plus actions that describe item cards. |
shoppable_video | A shoppable video creative with item-card actions. | video_url, a poster image, and actions that describe the item-card carousel. |
Request only the formats your storefront can render. Include shoppable_display, shoppable_video, or both in supported_format when you want shoppable creatives. For display image banners, see Display placements.
Request shoppable placements
Send a Get display placements request with placement_kind.display_placement.supported_format set to the formats you support. The following example requests shoppable display and shoppable video as interleaved placements:
curl --request POST \
--url https://<instacart_domain>/v2/ian/dp \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Retailer-Id: <retailer_slug>' \
--data '{
"page_context": {
"page_query": {
"search_query": {
"page_view_id": "4291d814-8a75-4fef-9426-123c5840f7bc",
"search_term": "ice cream",
"enable_auto_correct": true
}
}
},
"placement_context": {
"placement_kind": {
"display_placement": {
"supported_format": ["shoppable_display", "shoppable_video"],
"rectangle_query": {
"position": "interleaved"
}
}
}
},
"session_context": {
"user_id": "kamalsingh1234",
"user_ip": "192.0.2.146",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64)"
},
"store_context": {
"location_code": "111"
}
}'
If creatives is empty, no ad was returned for that request. For field details, see Get display placements.
A shoppable creative differs from a display image banner. Banner responses typically include image_display_banner_large and image_display_banner_small assets and a brand_page_click action. Shoppable responses include hero, logo, or video assets, item_card actions that you render as a product carousel, and an interaction_id on each action for event tracking. Shoppable creatives do not include display_position.
The following example shows the shoppable-specific parts of a Get display placements response for shoppable_video. A shoppable display creative uses image assets named hero_image and brand_logo instead of a video asset, plus the same item_card actions.
{
"creatives": [
{
"object_tracking_id": "urn:i-ic-v1:dcid:a/78219bd2-981d-49fb-a485-aaee5ddd8dfa",
"type": "shoppable_video.v4",
"assets": [
{
"name": "brand_logo",
"medium_properties": {
"image": {
"public_url": "https://cloudfront.net/logo.png",
"alt_text": "Brand logo"
}
}
},
{
"type": "image_video_thumbnail",
"medium_properties": {
"image": {
"public_url": "https://cloudfront.net/image.jpg",
"alt_text": "Brand story poster image"
}
}
},
{
"type": "video",
"medium_properties": {
"video": {
"video_url": "https://cloudfront.net/creative.mp4"
}
}
}
],
"actions": [
{
"name": "main_product_group_grid_x",
"interaction_id": "fc1f4b15-1c13-410f-bdc2-8457bbe95206",
"action_properties": {
"item_card": {
"position": 1,
"product_id": "30972167",
"rrc": "536071"
}
}
}
]
}
]
}
Rendering requirements
Each creative includes an assets array and an actions array. Use interaction_id from each action when you send events for that control. For each image asset, use the asset's alt_text as the rendered image alternative.
Shoppable display
- Render the
hero_imageandbrand_logoassets. - Display the tagline from the creative when it is present.
- Render item cards from
actionsthat includeaction_properties.item_card.
Shoppable video
- Render the player from
medium_properties.video.video_url. - Use the poster image until playback starts.
- Render the item-card carousel from
actionsthat includeaction_properties.item_card.
Do not infer image dimensions from a version field. When an image asset includes image_metadata, use width and height from that object.
Event mapping
Send events to Track ad events using the enums for that placement type. Shoppable display and shoppable video item events (add_creative_item, click_creative_item, viewport_1px_creative_item, and viewport_viewable_creative_item) follow the same trigger logic as display creative item events.
| Activity | When to send | Event type enum (shoppable video unless noted) |
|---|---|---|
| Video begins to render | The video starts playing. Send once per page load. | ian.display.viewport_video_begin_to_render |
| Video 1px in viewport | Any part of the video player is visible. Send once. Do not send if a modal blocks the player. | ian.display.viewport_1px_video |
| Video viewable in viewport | The player is in view for 2 continuous seconds. Send once. Do not send if a modal blocks the player. | ian.display.viewport_video_viewable |
| Video view completion | Playback reaches the end of the video. | ian.display.viewport_video_view_completion |
| Click the creative | The backend returns 200 to the frontend after the customer selects the creative. | ian.display.click_creative |
| Add an item from the carousel | The backend returns 200 after the customer adds the advertised item. | ian.display.add_creative_item |
For the full enum list by ad type, see Track ad events. For trigger logic that also applies to sponsored products and banners, see Events.