Get sponsored products
POST /v2/ian/sp
Retrieves sponsored products ad content that you can display in a component on your site, such as an item card or carousel. Specify the context in the request body.
Sponsored products are supported in the following contexts:
Name | Description | Page Query | Available Placement Types |
---|---|---|---|
Search | Ads are shown in the grid of search results. | SearchQuery | InGrid |
Buy It Again (department page) | Ads are shown in the grid on a dedicated Buy It Again page. | UserPreviouslyPurchasedQuery | InGrid |
Buy It Again (carousel) | Ads are shown in a Buy It Again carousel. | StorefrontQuery | InCarousel |
Browse | Ads are shown in the grid when a customer browses by category. | ProductCategoryQuery | InGrid |
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 |
---|---|---|---|
page_context | SponsoredProductsPageContext | ![]() | Specific page context for the requested ads. |
placement_context | SponsoredProductsPlacementContext | ![]() | Specific placement context for the requested ads. |
session_context | SessionContext | ![]() | Context related to the user session. |
store_context | StoreContext | ![]() | Context related to the selected store. |
SponsoredProductsPageContext Object
Field | Type | Required | Description |
---|---|---|---|
page_query | SponsoredProductsQuery | ![]() | Define one SponsoredProductsQuery object per request. This object sets the query for the page to show ads. |
filter_query | FilterQuery | ![]() | A query used to filter the returned ads to only those that match the filter. The filter query is independent of the page type. Note: To use the FilterQuery object, your catalog inventory file must contain the product tags, category IDs, or brand IDs that you want to use as filters. For more information, see the Filters concept in this documentation. |
ad_load_query | AdLoadQuery | ![]() | The query used to specify the number of ads to return. |
SponsoredProductsQuery Object
Field | Type | Required | Description |
---|---|---|---|
search_query | SearchQuery | ![]() | Specify only one of the options described in this table. This option retrieves the search page. Supported corresponding placement kind: ['in_grid']. |
user_previously_purchased_query | UserPreviouslyPurchasedQuery | ![]() | Specify only one of the options described in this table. This option retrieves the user previously purchased page. Supported corresponding placement kind: ['in_grid']. |
storefront_query | StorefrontQuery | ![]() | Specify only one of the options described in this table. This option retrieves the storefront page. Supported corresponding placement kind: ['mixed_ads_carousel']. |
product_category_query | ProductCategoryQuery | ![]() | Specify only one of the options described in this table. This option retrieves the product category page. Supported corresponding placement kind: ['in_grid']. |
SearchQuery Object
Field | Type | Required | Description |
---|---|---|---|
page_view_id | string | ![]() | Unique identifier of a search page view. Must be a UUID (Universal Unique Identifier). Required for retailers. Optional for third-party partners. |
search_term | string | ![]() | Search query term. |
enable_auto_correct | boolean | ![]() | Apply-auto correction for the input search term. This option increases the latency of the endpoint. Default is true. |
UserPreviouslyPurchasedQuery Object
Field | Type | Required | Description |
---|---|---|---|
page_view_id | string | ![]() | Unique identifier of a user previously purchased page view. Must be a UUID (Universal Unique Identifier). Required for retailers. Optional for third-party partners. |
StorefrontQuery Object
Field | Type | Required | Description |
---|---|---|---|
page_view_id | string | ![]() | Unique identifier of a retailer location storefront page view. Must be a UUID (Universal Unique Identifier). Required for retailers. Optional for third-party partners. |
ProductCategoryQuery Object
Field | Type | Required | Description |
---|---|---|---|
category_ids | Array(integer) | ![]() | Product category identifiers for the request. |
page_view_id | string | ![]() | Unique identifier of a retailer product category page view. Must be a UUID (Universal Unique Identifier). |
FilterQuery Object
Field | Type | Required | Description |
---|---|---|---|
filter_tags | FilterTags | ![]() | Filter tags that are used to filter the ads result. If a tag is included here, then sponsored products are included in the response only if the product has the corresponding tags. |
product_category_filter_query | ProductCategoryFilterQuery | ![]() | The query used to specify filters based off product_category_id's. It only applies to Search and BIA requests. |
brand_ids | Array(integer) | ![]() | An array of brand IDs to use to filter the available ads. Ads are returned if they match any of the brand IDs. |
FilterTags Object
Field | Type | Required | Description |
---|---|---|---|
tags | Array(string) | ![]() | An array of product attribute tags to use to filter the available ads. Ads are returned if the advertised product matches any of the product tags. |
ProductCategoryFilterQuery Object
Field | Type | Required | Description |
---|---|---|---|
category_ids | Array(integer) | ![]() | An array of product category IDs to use to filter the available ads. Ads are returned if an advertised product matches any of the category IDs. Only applies to Search and Buy It Again. Note: To specify product category filtering for the Product Category placement, use the PageQuery object rather than the FilterQuery object. |
AdLoadQuery Object
Field | Type | Required | Description |
---|---|---|---|
ads_count | string | ![]() | The maximum number of ads to return. The actual number of returned ads depends on the ad inventory available. |
SponsoredProductsPlacementContext Object
Field | Type | Required | Description |
---|---|---|---|
placement_kind | SponsoredProductsKind | ![]() | Define one SponsoredProductsKind object per request. This object sets the kind of placement for showing ads. |
SponsoredProductsKind Object
Field | Type | Required | Description |
---|---|---|---|
in_grid | InGrid | ![]() | Specify only one of the options described in this table. This option serves ads to show in the main grid of the page. Supported corresponding page query: ['search_query', 'user_previously_purchased_query', 'product_category_query']. |
mixed_ads_carousel | MixedAdsCarousel | ![]() | Specify only one of the options described in this table. This option serves ads to show in the carousel mixed with organic product. Supported corresponding page query: ['storefront_query']. |
InGrid Object
Field | Type | Required | Description |
---|---|---|---|
supported_format | Array(string) | ![]() | The ads format. Supported value: ['item_card']. |
MixedAdsCarousel Object
Field | Type | Required | Description |
---|---|---|---|
supported_format | Array(string) | ![]() | The ads format. Supported value: 'item_card'. |
carousel_query | InCarouselQuery | ![]() | Define one InCarouselQuery object per request. This object sets the organic query for the carousel that ads should be relevant to. |
InCarouselQuery Object
Field | Type | Required | Description |
---|---|---|---|
user_previously_purchased_query | UserPreviouslyPurchasedQuery | ![]() | Specify only one of the options described in this table. This option retrieves the user previously purchased page. |
SessionContext Object
Field | Type | Required | Description |
---|---|---|---|
user_id | string | ![]() | Unique user ID of the user performing the query. Maximum 50 characters. |
user_ip | string | ![]() | The IP address of the end user. Maximum 50 characters. |
user_agent | string | ![]() | The user agent of the device making the request. Maximum 50 characters. |
test_only | boolean | ![]() | When true, the campaigns created for Carrot Ads testing are guaranteed to participate in the ads auction along with other campaigns. Default is false. |
StoreContext Object
Field | Type | Required | Description |
---|---|---|---|
location_code | string | ![]() | The store location code used to perform the query. Maximum 100 characters. |
Request examples
curl --request POST \
--url https://connect-ian.instacart.com/v2/ian/sp \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Retailer-Id: string' \
--data '{
"page_context": {
"page_query": {
"search_query": {
"page_view_id": "string",
"search_term": "string",
"enable_auto_correct": true
}
},
"filter_query": {
"filter_tags": {
"tags": [
"string"
]
}
},
"ad_load_query": {
"ads_count": "string"
}
},
"placement_context": {
"placement_kind": {
"in_grid": {
"supported_format": [
"string"
]
}
}
},
"session_context": {
"user_id": "string",
"user_ip": "string",
"user_agent": "string",
"test_only": true
},
"store_context": {
"location_code": "string"
}
}'
Response
Field | Type | Required | Description |
---|---|---|---|
products | Array(SponsoredProduct) | ![]() | List of sponsored products. When no ads are returned, the response is an empty array. |
SponsoredProduct Object
Field | Type | Required | Description |
---|---|---|---|
object_tracking_id | string | ![]() | The unique tracking identifier for this ad. |
rrc | string | ![]() | Retailer reference code (RRC) which can be used by retailers to fetch additional metadata about the product from their own catalog. One of RRC or UPC is returned depending on configurations by the retailer. |
upc | string | ![]() | Non-normalized universal product code (UPC). One of RRC or UPC is returned depending on configurations by the retailer. |
product_id | integer | ![]() | Instacart product ID. |
display_position | integer | ![]() | Suggested display position when mixed with the organic products. The first position is 1. |
ad_format | string | ![]() | The ad format for this ad placement. Supported value: ['item_card']. |
Response examples
200 Success
200
Request with search page query and in_grid placement kind200
Request with user previously purchased page query and in_grid placement kind200
Request with storefront page query and mixed ads carousel placement kind
{
"products": [
{
"object_tracking_id": "urn:i-ic-v1:spid:78219bd2-981d-49fb-a485-aaee5ddd8dfa",
"rrc": "fake_rrc",
"product_id": 1,
"display_position": 1,
"ad_format": "item_card"
},
{
"object_tracking_id": "urn:i-ic-v1:spid:12319bd2-981d-49fb-a485-aaee5ddd8123",
"rrc": "fake_rrc_2",
"product_id": 2,
"display_position": 2,
"ad_format": "item_card"
}
]
}
{
"products": [
{
"object_tracking_id": "urn:i-ic-v1:spid:78219bd2-981d-49fb-a485-aaee5ddd8dfa",
"rrc": "fake_rrc",
"product_id": 1,
"display_position": 1,
"ad_format": "item_card"
}
]
}
{
"products": [
{
"object_tracking_id": "urn:i-ic-v1:spid:12319bd2-981d-49fb-a485-aaee5ddd8123",
"rrc": "fake_rrc_2",
"product_id": 2,
"display_position": 2,
"ad_format": "item_card"
}
]
}
4XX Errors
Error responses return either a single error or multiple errors.
HTTP Code | Cause | Error Message | Error Code | Error Meta |
---|---|---|---|---|
400 | invalid search page query with mixed ads carousel placement kind | "No internal placements match the given page query type and placement kind" | 1001 | Not applicable |
400 | invalid storefront page query with in grid placement kind | "No internal placements match the given page query type and placement kind" | 1001 | Not applicable |
400 | empty page query | "the number of attributes given for page_query is 0" | 1001 | {"key":"page_context.page_query"} |
400 | Request with more than one attribute used in page query | "the number of attributes given for page_query is 2" | 1001 | {"key":"page_context.page_query"} |
400 | empty placement kind | "the number of attributes given for placement_kind is 0" | 1001 | {"key":"placement_context.placement_kind"} |
400 | more than one attribute used in placement kind | "the number of attributes given for placement_kind is 2" | 1001 | {"key":"placement_context.placement_kind"} |
400 | too long user_id in the session context | "User ID length must be less than 51 characters" | 1001 | {"key":"session_context.user_id"} |
400 | too long location code in the store context | "Location code length must be less than 101 characters" | 1001 | {"key":"store_context.location_code"} |
401 | store that doesn't match the oauth token used | "the given location code doesn't match the oauth token used." | null | Not applicable |