Track ad events

POST /v2/ian/track

Sends ad-related events from a retailer's site to Instacart. Events capture user actions such as clicks, add-to-cart actions, backend served impressions, and frontend viewport impressions (1 pixel and viewable). The events are used for billing, generating metrics, training machine learning models, and auditing purposes.

Events types

The following table lists the supported event types for each ad type:

Ad type	Values
Sponsored product	ian.sponsored_product.viewable_in_viewport ian.sponsored_product.begin_to_render_viewport ian.sponsored_product.1px_in_viewport ian.sponsored_product.clicked ian.sponsored_product.added_to_cart
Display banner	ian.display.click_creative ian.display.viewport_load_creative ian.display.viewport_1px_creative ian.display.viewport_viewable_creative ian.display.viewport_viewable_creative_asset ian.display.viewport_viewable_begin_to_render_creative ian.display.viewport_viewable_begin_to_render_creative_asset
Shoppable display	ian.display.click_creative ian.display.viewport_load_creative ian.display.viewport_1px_creative ian.display.viewport_viewable_creative ian.display.viewport_viewable_creative_asset ian.display.viewport_viewable_begin_to_render_creative ian.display.viewport_viewable_begin_to_render_creative_asset
Shoppable display item	ian.display.add_creative_item ian.display.click_creative_item ian.display.viewport_1px_creative_item ian.display.viewport_viewable_creative_item

Security

Name	In	Description
Authorization	header	The Authorization header with the bearer token acquired during authentication.

Parameters

Name	In	Type	Required	Description
X-Retailer-Id	header	string		The retailer slug. This is only required for a retailer with multiple banners. Retailers with single banners can leave this empty.

Request

Field	Type	Required	Description
event	string		The type of the event. Supported values for SP: ['ian.sponsored_product.viewable_in_viewport', 'ian.sponsored_product.begin_to_render_viewport', 'ian.sponsored_product.1px_in_viewport', 'ian.sponsored_product.clicked', 'ian.sponsored_product.added_to_cart']. Supported values for display banner: ['ian.display.viewport_load_creative', 'ian.display.viewport_1px_creative', 'ian.display.viewport_viewable_creative', 'ian.display.viewport_viewable_creative_asset', 'ian.display.click_creative', 'ian.display.viewport_viewable_begin_to_render_creative', 'ian.display.viewport_viewable_begin_to_render_creative_asset']. Supported values for shoppable display: ['ian.display.viewport_load_creative', 'ian.display.viewport_1px_creative', 'ian.display.viewport_viewable_creative', 'ian.display.viewport_viewable_creative_asset', 'ian.display.click_creative', 'ian.display.viewport_viewable_begin_to_render_creative', 'ian.display.viewport_viewable_begin_to_render_creative_asset']. Supported values for shoppable video: ['ian.display.viewport_load_creative', 'ian.display.viewport_1px_creative', 'ian.display.viewport_viewable_creative', 'ian.display.click_creative', 'ian.display.viewport_viewable_begin_to_render_creative_asset', 'ian.display.viewport_video_begin_to_render', 'ian.display.viewport_1px_video', 'ian.display.viewport_video_viewable']. Supported values for shoppable display item: ['ian.display.add_creative_item', 'ian.display.click_creative_item', 'ian.display.viewport_1px_creative_item', 'ian.display.viewport_viewable_creative_item']. Supported values for shoppable video item: ['ian.display.add_creative_item', 'ian.display.click_creative_item', 'ian.display.viewport_1px_creative_item', 'ian.display.viewport_viewable_creative_item'].
data	EventData		The data of the event. Required for retailers. Optional for third-party partners.
user_id	string		The unique user ID. Maximum 50 characters.
sent_at	string		The time when the client fired the event. Use ISO8601 format with the time zone designator (TZD) appended. Example: 2022-12-03T10:15:30+08:00.

EventData Object

Field	Type	Required	Description
sponsored_product_data	FeaturedProductEventProperties		Specify only one of the options described in this table. This option retrieves event data for sponsored product events.
display_banner_data	DisplayBannerEventProperties		Specify only one of the options described in this table. This option retrieves event data for display events.
shoppable_display_data	ShoppableDisplayEventData		Specify only one of the options described in this table. This option retrieves event data for shoppable display events.
shoppable_video_data	ShoppableVideoEventData		Specify only one of the options described in this table. This option retrieves event data for shoppable video events.
shoppable_display_item_data	ShoppableDisplayItemEventData		Specify only one of the options described in this table. This option retrieves event data for shoppable display item events.
shoppable_video_item_data	ShoppableVideoItemEventData		Specify only one of the options described in this table. This option retrieves event data for shoppable video item events.

FeaturedProductEventProperties Object

Field	Type	Required	Description
event_tracking_context	EventTrackingContext		Common context about the event.
event_id	string		The UUID (Universal Unique Identifier) for the event.
object_tracking_id	string		The tracking ID of the ad that was clicked on.
display_position	string		The position of the sponsored product in the item grid.
organic_position	string		The original position of the organic item that was deduped by the sponsored product.
format_type	string		The format of the sponsored product that was shown.
product_id	string		The product ID of product shown as a sponsored product. This is the same as the product ID returned in the sponsored product response for an ad item.
page	string		The page on which the sponsored product was shown, where the first page is 1. The value must be greater than 0.
block_number	string		The sequential block number of which the sponsored product was a part.
record_version	string		The version of the event record. Set to 1 for production events. Set to 999 for testing events. Any other value returns an error code.
page_view_id	string		The page view ID where the ad was shown.

EventTrackingContext Object

Field	Type	Required	Description
user_agent	string		The user agent of the device making the request.
user_ip	string		The IP address of the end user.

DisplayBannerEventProperties Object

Field	Type	Required	Description
event_tracking_context	EventTrackingContext		Common context about the event.
object_tracking_id	string		The tracking ID of the display ad.
creative_type	string		Type of the creative.
interaction_id	string		Represents a unique identifier of the action instance rendered in a client and interacted with. This field is required for the following events: ['ian.display.click_creative'].
page_view_id	string		Unique identifier of a page view.
search_term	string		Search term associated with the request.
event_id	string		The unique uuid for the event.
record_version	string		The version of the event record. Set to 1 for production events. Set to 999 for testing events. Any other value returns an error code.
asset_type	string		The asset type of the event from the “type” field of the asset object in the display ads response. Required for events at the asset level (ex: 'ian.display.viewport_viewable_begin_to_render_creative_asset' and 'ian.display.viewport_viewable_creative_asset').

ShoppableDisplayEventData Object

Field	Type	Required	Description
event_tracking_context	EventTrackingContext		Common context about the event.
event_id	string		The unique uuid for the event.
object_tracking_id	string		The tracking ID of the display shoppable ad.
record_version	string		The version of the event record. Set to 1 for production events. Set to 999 for testing events. Any other value returns an error code.
page_view_id	string		Unique identifier of a page view.
interaction_id	string		Represents a unique identifier of the action instance rendered in a client and interacted with. This field is required for the following events: ['ian.display.click_creative'].
creative_type	string		The creative type of the event from the “type” field of the creative object in the display ads response.
asset_type	string		The asset type of the event from the “type” field of the asset object in the display ads response. Required for events at the asset level (ex: 'ian.display.viewport_viewable_begin_to_render_creative_asset' and 'ian.display.viewport_viewable_creative_asset').

ShoppableVideoEventData Object

Field	Type	Required	Description
event_tracking_context	EventTrackingContext		Common context about the event.
event_id	string		The unique uuid for the event.
object_tracking_id	string		The tracking ID of the display shoppable ad.
record_version	string		The version of the event record. Please use 1 for production events and 999 for testing events.
page_view_id	string		Unique identifier of a page view.
interaction_id	string		Represents a unique identifier of the action instance rendered in a client and interacted with. This field is required for the following events: ['ian.display.click_creative'].
creative_type	string		The creative type of the event from the “type” field of the creative object in the display ads response.
asset_type	string		The asset type of the event from the “type” field of the asset object in the display ads response. Required for events at the asset level (ex: 'ian.display.viewport_viewable_begin_to_render_creative_asset' and 'ian.display.viewport_viewable_creative_asset').

ShoppableDisplayItemEventData Object

Field	Type	Required	Description
event_tracking_context	EventTrackingContext		Common context about the event.
event_id	string		The unique uuid for the event.
object_tracking_id	string		The tracking ID of the display shoppable ad.
record_version	string		The version of the event record. Set to 1 for production events. Set to 999 for testing events. Any other value returns an error code.
page_view_id	string		Unique identifier of a page view.
interaction_id	string		Represents a unique identifier of the action instance rendered in a client and interacted with. This field is required for the following events: ['ian.display.add_creative_item', 'ian.display.click_creative_item'].
creative_type	string		The creative type of the event from the “type” field of the creative object in the display ads response.
product_id	string		The product ID corresponding to the display shoppable ad event.

ShoppableVideoItemEventData Object

Field	Type	Required	Description
event_tracking_context	EventTrackingContext		Common context about the event.
event_id	string		The unique uuid for the event.
object_tracking_id	string		The tracking ID of the display shoppable ad.
record_version	string		The version of the event record. Please use 1 for production events and 999 for testing events.
page_view_id	string		Unique identifier of a page view.
interaction_id	string		Represents a unique identifier of the action instance rendered in a client and interacted with. This field is required for the following events: ['ian.display.add_creative_item', 'ian.display.click_creative_item'].
creative_type	string		The creative type of the event from the “type” field of the creative object in the display ads response.
product_id	string		The product ID corresponding to the display shoppable ad event.

Request examples

curl --request POST \
  --url https://connect-ian.instacart.com/v2/ian/track \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: string' \
  --header 'X-Retailer-Id: string' \
  --data '{
  "event": "string",
  "data": {
    "sponsored_product_data": {
      "event_tracking_context": {
        "user_agent": "string",
        "user_ip": "string"
      },
      "object_tracking_id": "string",
      "display_position": "string",
      "organic_position": "string",
      "format_type": "item_card",
      "product_id": "string",
      "page": "string",
      "block_number": "string",
      "record_version": "string",
      "page_view_id": "string"
    }
  },
  "user_id": "string",
  "sent_at": "string"
}'

Response

Field	Type	Required	Description
message	string		Response for the user.

Response examples

200 Success

200 Tracked view event

{
  "message": "Successfully processed"
}

200 Tracked click event

{
  "message": "Successfully processed"
}

200 Tracked add to cart event

{
  "message": "Successfully processed"
}

200 Tracked viewable viewport event

{
  "message": "Successfully processed"
}

200 Tracked 1px viewport viewable event

{
  "message": "Successfully processed"
}

200 Tracked viewport tracking event

{
  "message": "Successfully processed"
}

200 Tracked begin to render viewport event

{
  "message": "Successfully processed"
}

200 Tracked view event with all optional fields included

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for search/boosted search

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for search/frequently bought with

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for aisle/aisle

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for aisle/boosted aisle

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for department/boosted aisle

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for department/aisle

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for department/boosted your items

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for store root department/boosted your items

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for store root department/boosted aisle

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for store root/aisle

{
  "message": "Successfully processed"
}

200 Event with correct page and placement type for item detail/aisle

{
  "message": "Successfully processed"
}

200 Accepts a string user id

{
  "message": "Successfully processed"
}

200 Tracked brand page view

{
  "message": "Successfully processed"
}

200 Tracked brand page click

{
  "message": "Successfully processed"
}

200 Tracked display creative view

{
  "message": "Successfully processed"
}

200 Tracked video view

{
  "message": "Successfully processed"
}

200 Tracked display creative item view

{
  "message": "Successfully processed"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Missing event data*	"There were issues with your request"	9999	Not applicable
400	Extra event data*	"There were issues with your request"	9999	Not applicable
400	No event params	"Couldn't find user_id in the request"	4001	Not applicable
400	Missing event context	"can't be blank"	1001	{"key":"data.shoppable_video_item_data.event_tracking_context"}
400	Invalid ad id	"must be a UUID"	1001	{"key":"data.sponsored_product_data.ad_id"}
400	Invalid display position	"is not a number"	1001	{"key":"data.sponsored_product_data.display_position"}
400	Invalid organic position	"Invalid organic position given."	1001	{"key":"data.sponsored_product_data.organic_position"}
400	Invalid format type	"is not included in the list"	1001	{"key":"data.sponsored_product_data.format_type"}
400	Invalid product id	"is not a number"	1001	{"key":"data.sponsored_product_data.product_id"}
400	product_id can't be a decimal	"must be an integer"	1001	{"key":"data.sponsored_product_data.product_id"}
400	product_id is a number under 1	"must be greater than or equal to 1"	1001	{"key":"data.sponsored_product_data.product_id"}
400	Invalid search id	"must be a UUID"	1001	{"key":"data.sponsored_product_data.search_id"}
400	Invalid event name	"Invalid event name Clicked an ad"	1001	{"key":"data"}
400	Invalid page type	"is not included in the list"	1001	{"key":"data.display_banner_data.page_type"}
400	Invalid placement type	"Improper placement reported for search"	1001	{"key":"data.sponsored_product_data"}
400	Invalid platform	"is not included in the list"	1001	{"key":"data.display_banner_data.platform"}
400	Invalid block number	"is not a number"	1001	{"key":"data.sponsored_product_data.block_number"}
400	Invalid record version type	"is not a number"	1001	{"key":"data.sponsored_product_data.record_version"}
400	Invalid page view ID	"must be a UUID or 'None'"	1001	{"key":"data.sponsored_product_data.page_view_id"}
400	Invalid mgs correlation ID	"must be a UUID"	1001	{"key":"data.sponsored_product_data.mgs_correlation_id"}
400	Improper placement for search	"Improper placement reported for search"	1001	{"key":"data.sponsored_product_data"}
400	User agent is too long	"is too long (maximum is 1000 characters)"	1001	{"key":"data.sponsored_product_data.event_tracking_context.user_agent"}
400	Tracked brand page view event with item/product id	"Item/product id should be empty for client brand page view event type"	1001	{"key":"data"}
400	Tracked brand page click with no item/product id	"Item/product id field should not be empty"	1001	{"key":"data"}
400	Invalid UUID field	"must be a UUID"	1001	{"key":"data.brand_page_data.session_token"}
400	Invalid UUID for interaction id	"must be a UUID"	1001	{"key":"data.shoppable_video_item_data.interaction_id"}
400	Invalid creative type	"is not included in the list"	1001	{"key":"data.shoppable_video_item_data.creative_type"}
400	Invalid asset type	"is not included in the list"	1001	{"key":"data.shoppable_display_data.asset_type"}
400	Invalid UUID for event id	"must be a UUID"	1001	{"key":"data.shoppable_video_item_data.event_id"}
400	Missing product id	"can't be blank"	1001	{"key":"data.shoppable_video_item_data.product_id"}

* Multiple error