Events
Carrot Ads API events occur when a user sees or engages with an ad, such as viewing an ad, clicking an ad, or adding an advertised product to a cart. Whenever an event occurs, your e-commerce site sends the event to Instacart. The events are used for billing, generating ads metrics, training machine learning models, and auditing purposes.
Types of events
The following table describes the types of events that can be sent for an ad. For the detailed list of event enums for each type of ad, see Track ads events.
| Event type | Description |
|---|---|
| Click | The user clicks an ad. |
| Add to cart | The user adds the advertised product to their cart. |
| Begin to render viewport (BTR) | The ad renders on the web or app. |
| 1px in viewport | The user views a single pixel of the ad. |
| Viewable in viewport | At least 50% of the ad is visible to the user for more than 1 second. |
When to send ad events
Whenever an ad is displayed to a user or a user successfully engages with an ad, send the ad event immediately. Timely and accurate events are critical for billing purposes and for returning recommendations.
For example, the following table describes the types of activities that trigger events for sponsored products and when to send the event:
| Activity | Event type enum | Implementation logic |
|---|---|---|
| User clicks the sponsored item card (not the add button) | ian.sponsored_product.clicked | Send the event after the backend has returned a 200 response back to the frontend. |
| User adds the sponsored item to a cart | ian.sponsored_product.added_to_cart | Send the event after the backend has returned a 200 response to the frontend. |
| User increases the quantity of sponsored item using the "+" button | ian.sponsored_product.added_to_cart | Send the event after the backend has returned a 200 response to the frontend. Send each time the quantity is incremented. For example, if the user clicks the add button twice, send the event twice. |
| Frontend is rendered with Ads | ian.sponsored_product.begin_to_render_viewport | Send the event for each ad loaded on the user app or website. Send once per page load. If the server side sends four pages of results that are going to be paginated, send events for whichever pages are rendered. For example, if page 1 is rendered and displayed on screen, page 2 is rendered in the background, and page 3 and 4 are cached on the backend, then pages 1 and 2 send the event, but pages 3 and 4 don't send the event until rendered. |
| User views 1px of the sponsored item | ian.sponsored_product.1px_in_viewport | Send the event for each ad when any portion of the ad is viewed. Send once per page load. If the sponsored item is blocked by a modal, don't send this event. |
| User views more than 50% of the sponsored item for more than 1s | ian.sponsored_product.viewable_in_viewport | Send the event for each ad when half of the ad is viewed for > 1s. Send once per page load. If the sponsored item is blocked by a modal, don't send this event. |
Don't send ad events when the user performs the following actions:
- Decreases the quantity of a sponsored item by using "-" button on the item card.
- Adds the same item to cart after landing on a sponsored product detail page.
- Increases or decreases the sponsored item quantity from the checkout cart.
- Clicks or adds to cart the retailer's organic ad for the sponsored item on the same surface or another surface.
If you experience downtime, send the events as soon as service is restored. You might want to use a separate process for the backlogged events to avoid interference with sending new events.
Ad Event Sequence Diagram
The sequence diagram walks through the events that are sent when a page or carousel is rendered with Carrot Ads in it. To avoid ad blockers, the events are routed from the retailer's backend system. On the Instacart side, the requests are received through the Instacart Connect platform and routed to the Carrot Ad services. For more information about Instacart Connect, see the Connect documentation.
Optionally, retailers can decide to send the events to a customer data platform (CDP), such as Segment, and then send the events to Instacart.
To view the sequence diagram, see Ad Event Sequence Diagram.