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

200 Request with user previously purchased page query and in_grid 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"
    }
  ]
}

200 Request with storefront page query and mixed ads carousel placement kind

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