Skip to main content

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:

NameDescriptionPage QueryAvailable Placement Types
SearchAds are shown in the grid of search results.SearchQueryInGrid
Buy It Again (department page)Ads are shown in the grid on a dedicated Buy It Again page.UserPreviouslyPurchasedQueryInGrid
Buy It Again (carousel)Ads are shown in a Buy It Again carousel.StorefrontQueryInCarousel
BrowseAds are shown in the grid when a customer browses by category.ProductCategoryQueryInGrid

Security

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters

NameInTypeRequiredDescription
X-Retailer-IdheaderstringOptionalThe retailer slug. This is only required for a retailer with multiple banners. Retailers with single banners can leave this empty.

Request

FieldTypeRequiredDescription
page_contextSponsoredProductsPageContextRequiredSpecific page context for the requested ads.
placement_contextSponsoredProductsPlacementContextRequiredSpecific placement context for the requested ads.
session_contextSessionContextRequiredContext related to the user session.
store_contextStoreContextRequiredContext related to the selected store.

SponsoredProductsPageContext Object

FieldTypeRequiredDescription
page_querySponsoredProductsQueryRequiredDefine one SponsoredProductsQuery object per request. This object sets the query for the page to show ads.
filter_queryFilterQueryOptionalA 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_queryAdLoadQueryOptionalThe query used to specify the number of ads to return.

SponsoredProductsQuery Object

FieldTypeRequiredDescription
search_querySearchQueryOptionalSpecify only one of the options described in this table. This option retrieves the search page. Supported corresponding placement kind: ['in_grid'].
user_previously_purchased_queryUserPreviouslyPurchasedQueryOptionalSpecify only one of the options described in this table. This option retrieves the user previously purchased page. Supported corresponding placement kind: ['in_grid'].
storefront_queryStorefrontQueryOptionalSpecify only one of the options described in this table. This option retrieves the storefront page. Supported corresponding placement kind: ['mixed_ads_carousel'].
product_category_queryProductCategoryQueryOptionalSpecify only one of the options described in this table. This option retrieves the product category page. Supported corresponding placement kind: ['in_grid'].

SearchQuery Object

FieldTypeRequiredDescription
page_view_idstringOptionalUnique identifier of a search page view. Must be a UUID (Universal Unique Identifier). Required for retailers. Optional for third-party partners.
search_termstringRequiredSearch query term.
enable_auto_correctbooleanOptionalApply-auto correction for the input search term. This option increases the latency of the endpoint. Default is true.

UserPreviouslyPurchasedQuery Object

FieldTypeRequiredDescription
page_view_idstringOptionalUnique 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

FieldTypeRequiredDescription
page_view_idstringOptionalUnique 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

FieldTypeRequiredDescription
category_idsArray(integer)RequiredProduct category identifiers for the request.
page_view_idstringOptionalUnique identifier of a retailer product category page view. Must be a UUID (Universal Unique Identifier).

FilterQuery Object

FieldTypeRequiredDescription
filter_tagsFilterTagsOptionalFilter 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_queryProductCategoryFilterQueryOptionalThe query used to specify filters based off product_category_id's. It only applies to Search and BIA requests.
brand_idsArray(integer)OptionalAn array of brand IDs to use to filter the available ads. Ads are returned if they match any of the brand IDs.

FilterTags Object

FieldTypeRequiredDescription
tagsArray(string)RequiredAn 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

FieldTypeRequiredDescription
category_idsArray(integer)RequiredAn 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

FieldTypeRequiredDescription
ads_countstringOptionalThe maximum number of ads to return. The actual number of returned ads depends on the ad inventory available.

SponsoredProductsPlacementContext Object

FieldTypeRequiredDescription
placement_kindSponsoredProductsKindRequiredDefine one SponsoredProductsKind object per request. This object sets the kind of placement for showing ads.

SponsoredProductsKind Object

FieldTypeRequiredDescription
in_gridInGridOptionalSpecify 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_carouselMixedAdsCarouselOptionalSpecify 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

FieldTypeRequiredDescription
supported_formatArray(string)RequiredThe ads format. Supported value: ['item_card'].

MixedAdsCarousel Object

FieldTypeRequiredDescription
supported_formatArray(string)RequiredThe ads format. Supported value: 'item_card'.
carousel_queryInCarouselQueryRequiredDefine one InCarouselQuery object per request. This object sets the organic query for the carousel that ads should be relevant to.

InCarouselQuery Object

FieldTypeRequiredDescription
user_previously_purchased_queryUserPreviouslyPurchasedQueryOptionalSpecify only one of the options described in this table. This option retrieves the user previously purchased page.

SessionContext Object

FieldTypeRequiredDescription
user_idstringRequiredUnique user ID of the user performing the query. Maximum 50 characters.
user_ipstringRequiredThe IP address of the end user. Maximum 50 characters.
user_agentstringRequiredThe user agent of the device making the request. Maximum 50 characters.
test_onlybooleanOptionalWhen 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

FieldTypeRequiredDescription
location_codestringRequiredThe 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

FieldTypeRequiredDescription
productsArray(SponsoredProduct)OptionalList of sponsored products. When no ads are returned, the response is an empty array.

SponsoredProduct Object

FieldTypeRequiredDescription
object_tracking_idstringRequiredThe unique tracking identifier for this ad.
rrcstringOptionalRetailer 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.
upcstringOptionalNon-normalized universal product code (UPC). One of RRC or UPC is returned depending on configurations by the retailer.
product_idintegerRequiredInstacart product ID.
display_positionintegerRequiredSuggested display position when mixed with the organic products. The first position is 1.
ad_formatstringOptionalThe ad format for this ad placement. Supported value: ['item_card'].

Response examples

200 Success

{
"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"
}
]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400invalid search page query with mixed ads carousel placement kind"No internal placements match the given page query type and placement kind"1001Not applicable
400invalid storefront page query with in grid placement kind"No internal placements match the given page query type and placement kind"1001Not applicable
400empty page query"the number of attributes given for page_query is 0"1001{"key":"page_context.page_query"}
400Request 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"}
400empty placement kind"the number of attributes given for placement_kind is 0"1001{"key":"placement_context.placement_kind"}
400more than one attribute used in placement kind"the number of attributes given for placement_kind is 2"1001{"key":"placement_context.placement_kind"}
400too long user_id in the session context"User ID length must be less than 51 characters"1001{"key":"session_context.user_id"}
400too long location code in the store context"Location code length must be less than 101 characters"1001{"key":"store_context.location_code"}
401store that doesn't match the oauth token used"the given location code doesn't match the oauth token used."nullNot applicable