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`
Candidate Carousel	Ads are shown in a carousel based on provided UPC list.	`CandidateCarouselQuery`	`MixedAdsCarousel`

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	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	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	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'].
`candidate_carousel_query`	CandidateCarouselQuery	Specify a list of desired UPCs to display in the carousel. For the Candidate Carousel Query the responses are based on the UPC list provided: Provided UPC list contains all ad-eligible items: All appear in the response, ranked by SP auction Provided UPC list contains no eligible items: Response is (empty payload) Provided UPC list is mixed eligibility: Only eligible items returned; others ignored UPC list contains duplicates: Duplicates are deduplicated before auction Location code does not match an active Thrive facility: Response is (empty payload)

SearchQuery Object

Field	Type	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. Defaults to 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).

CandidateCarouselQuery Object

Field	Type	Required	Description
`page_view_id`	string		Page view id for ad event tracking. Must be a UUID (Universal Unique Identifier). Required for retailers. Optional for third-party partners.
`upc_list`	Array(string)		List of UPCs to display in the carousel.

FilterQuery Object

Field	Type	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. This filter is only applicable to shoppable display and shoppable video requests.
`product_category_filter_query`	ProductCategoryFilterQuery	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.
`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. This filter is only applicable to shoppable display and shoppable video requests.

FilterTags Object

Field	Type	Required	Description
`tags`	Array(string)		An array of tags or filter names as strings.

ProductCategoryFilterQuery Object

Field	Type	Required	Description
`category_ids`	Array(integer)		Product category IDs for the request.

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	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	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. Either RRC or UPC is returned depending on the retailer's configuration.
`upc`	string	Non-normalized universal product code (UPC). Either RRC or UPC is returned depending on the retailer's configuration.
`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
200 Request with user previously purchased page query and in_grid placement kind
200 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

Security​

Parameters​

Request​

SponsoredProductsPageContext Object​

SponsoredProductsQuery Object​

SearchQuery Object​

UserPreviouslyPurchasedQuery Object​

StorefrontQuery Object​

ProductCategoryQuery Object​

CandidateCarouselQuery Object​

FilterQuery Object​

FilterTags Object​

ProductCategoryFilterQuery Object​

AdLoadQuery Object​

SponsoredProductsPlacementContext Object​

SponsoredProductsKind Object​

InGrid Object​

MixedAdsCarousel Object​

InCarouselQuery Object​

SessionContext Object​

StoreContext Object​

Request examples​

Response​

SponsoredProduct Object​

Response examples​