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`	`MixedAdsCarousel`
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`	`InGrid`, `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	The page context for the ad request, including the page type, filters, and ad load configuration.
`placement_context`	SponsoredProductsPlacementContext	The placement configuration for the ad request. The placement kind must be compatible with the selected page query type.
`session_context`	SessionContext	The user session information, including user ID, IP address, and user agent string.
`store_context`	StoreContext	The store context identifying the retail location for the ad request.
`pagination_context`	PaginationContext	The pagination parameters for fetching a specific page of ads. On the first request, omit the token to receive a fresh result set and a session token. On subsequent requests, include the token and advance the offset to retrieve additional pages.

SponsoredProductsPageContext Object

Field	Type	Description
`page_query`	SponsoredProductsQuery	The page type for the ad request. Exactly one page query option must be specified (for example, search_query or storefront_query). The selected option determines which ads are eligible to be served.
`filter_query`	FilterQuery	Filters to narrow the returned ads. Supports tag-based, category-based, or brand-based filtering. Filters are applied independently of the page type. Your catalog inventory file must include the corresponding tags, category IDs, or brand IDs for filtering to take effect.
`ad_load_query`	AdLoadQuery	Controls the maximum number of ads returned in the response.

SponsoredProductsQuery Object

Field	Type	Description
`search_query`	SearchQuery	Retrieves sponsored product ads for a search results page. Must be paired with the 'in_grid' placement kind. Only one page query option may be specified per request.
`user_previously_purchased_query`	UserPreviouslyPurchasedQuery	Retrieves sponsored product ads for a Buy It Again or previously purchased products page. Must be paired with the 'in_grid' placement kind. Only one page query option may be specified per request.
`storefront_query`	StorefrontQuery	Retrieves sponsored product ads for the storefront page. Must be paired with the 'mixed_ads_carousel' placement kind. Only one page query option may be specified per request.
`product_category_query`	ProductCategoryQuery	Retrieves sponsored product ads for a product category or browse page. Must be paired with the 'in_grid' placement kind. Only one page query option may be specified per request.
`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	A unique identifier for the current page view. Must be a valid UUID. Pass the string 'None' if a page view identifier is not available.
`search_term`	string	The search term entered by the user. Ads are matched based on relevance to this term.
`enable_auto_correct`	boolean	When set to true, auto-correction is applied to the search term to improve matching for misspellings. Defaults to true. Enabling auto-correction increases response latency.

UserPreviouslyPurchasedQuery Object

Field	Type	Required	Description
`page_view_id`	string		A unique identifier for the current page view. Must be a valid UUID. Pass the string 'None' if a page view identifier is not available.

StorefrontQuery Object

Field	Type	Required	Description
`page_view_id`	string		A unique identifier for the current page view. Must be a valid UUID. Pass the string 'None' if a page view identifier is not available.

ProductCategoryQuery Object

Field	Type	Required	Description
`category_ids`	Array(integer)		An array of product category IDs for the category page being viewed. Sponsored products are matched based on these categories.
`page_view_id`	string		A unique identifier for the current page view. Must be a valid UUID. Pass the string 'None' if a page view identifier is not available.

CandidateCarouselQuery Object

Field	Type	Required	Description
`page_view_id`	string		A unique identifier for the current page view. Must be a valid UUID. Pass the string 'None' if a page view identifier is not available.
`upc_list`	Array(string)		An array of UPC strings identifying the products eligible for the carousel ad auction.

FilterQuery Object

Field	Type	Description
`filter_tags`	FilterTags	Filters ad results by product tags. When specified, only products matching at least one tag are returned. The object must contain a 'tags' array. Example: { "filter_tags": { "tags": ["tag1", "tag2"] } }. Not applicable to display banner requests.
`product_category_filter_query`	ProductCategoryFilterQuery	Filters available ads by product category. Ads are returned only if the advertised product matches at least one of the specified category IDs. Applies to search, Buy It Again, and storefront placements. For product category placements, specify category IDs in the PageQuery object.
`brand_ids`	Array(integer)	An array of brand IDs to filter available ads. Ads are returned only if they match at least one of the specified brand IDs.

FilterTags Object

Field	Type	Required	Description
`tags`	Array(string)		An array of tag strings. Only products matching at least one of the specified tags are returned.

ProductCategoryFilterQuery Object

Field	Type	Required	Description
`category_ids`	Array(integer)		An array of product category IDs. Ads are returned only if the advertised product belongs to at least one of the specified categories.

AdLoadQuery Object

Field	Type	Required	Description
`ads_count`	string		The maximum number of ads to return, specified as a string (for example, "10"). Must be an integer value between 1 and 100. The actual number of ads returned may be lower depending on available inventory.

SponsoredProductsPlacementContext Object

Field	Type	Required	Description
`placement_kind`	SponsoredProductsKind		Specifies how sponsored product ads are displayed on the page. Exactly one placement option must be provided: 'in_grid' for ads within a product grid, or 'mixed_ads_carousel' for ads within a carousel.

SponsoredProductsKind Object

Field	Type	Required	Description
`in_grid`	InGrid		Displays sponsored product ads inline within the main product grid. Only one placement option may be specified per request. Must be paired with one of the following page queries: search_query, user_previously_purchased_query, product_category_query, or candidate_carousel_query.
`mixed_ads_carousel`	MixedAdsCarousel		Displays sponsored product ads in a carousel alongside organic products. Only one placement option may be specified per request. Must be paired with the storefront_query or candidate_carousel_query page query.

InGrid Object

Field	Type	Required	Description
`supported_format`	Array(string)		The ad format for the placement, specified as an array. The supported value is ["item_card"].

MixedAdsCarousel Object

Field	Type	Required	Description
`supported_format`	Array(string)		The ad format for the placement, specified as an array. The supported value is ["item_card"].
`carousel_query`	InCarouselQuery		The organic product context for the carousel. Ads are matched to be relevant to this context. Typically uses a user_previously_purchased_query.

InCarouselQuery Object

Field	Type	Required	Description
`user_previously_purchased_query`	UserPreviouslyPurchasedQuery		Provides previously purchased product context for the carousel. Only one option may be specified per request.

SessionContext Object

Field	Type	Description
`user_id`	string	A unique identifier for the end user. Maximum 50 characters.
`user_ip`	string	The IP address of the end user. Must be a valid IPv4 or IPv6 address.
`user_agent`	string	The User-Agent string from the end user's device. Maximum 1000 characters.
`test_only`	boolean	When set to true, only test campaigns are returned in the response. Regular campaigns are excluded. Use this to validate your integration without serving live ads. Defaults to false.

StoreContext Object

Field	Type	Required	Description
`location_code`	string		The store location code for the retail location to retrieve ads for. Must match a location code associated with your account. Maximum 100 characters.

PaginationContext Object

Field	Type	Description
`page_size`	integer	Number of ads to return per page. Defaults to the placement's configured page size when omitted.
`offset`	integer	How far into the result set to advance, expressed in whole pages, starting at 1. An offset of 1 returns the first page, 2 returns the second, and so on. Defaults to 1 when omitted.
`token`	string	Opaque session token returned by a previous paginated response. Include this token in subsequent requests to retrieve pages from the same cached result set. Omit on the first request to begin a new pagination session.

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"
  },
  "pagination_context": {
    "page_size": 10,
    "offset": 1
  }
}'

Pagination

You can page through ad results using pagination_context on the request body and pagination_metadata in the response. Field descriptions for both objects appear in the request and response tables in this topic.

Pagination behavior

tip

On the first request, omit the token to receive a fresh result set and a session token. On subsequent requests, include the token and advance the offset to retrieve additional pages.

The following rules also apply when using pagination:

Expired session token. If the token from a previous response is no longer valid, the request is treated as a new auction (a fresh result set), not as a dedicated "expired token" error response.
Page beyond available ads. If you request a page past the last page of results, the API returns a successful response with an empty results array (not an error).

When pagination applies, the response includes pagination_metadata with token (pass in the next request's pagination_context.token) and offset (the page position returned for this response). To advance to the next page, increment offset by 1 in the following request.

For this endpoint, a page beyond the last page of results returns an empty products array.

Response

Field	Type	Required	Description
`products`	Array(SponsoredProduct)		An array of sponsored product objects. Returns an empty array when no ads are available.
`pagination_metadata`	PaginationMetadata		Pagination output containing the session token and current page position. Pass the returned token and an incremented offset in follow-up requests to retrieve the next page.

SponsoredProduct Object

Field	Type	Description
`object_tracking_id`	string	The unique tracking identifier for this ad. Use this value when reporting ad events such as impressions and clicks.
`rrc`	string	The retailer reference code (RRC) for the advertised product. Use this to look up product details in your catalog. Populated based on your account configuration.
`upc`	string	The universal product code (UPC) for the advertised product, returned in its original format without normalization. Populated based on your account configuration.
`product_id`	integer	The Instacart product ID for the advertised product.
`display_position`	integer	The suggested 1-based position for this ad when displayed alongside organic products. For example, a value of 3 means the ad should appear in the third slot.
`ad_format`	string	The ad format for this ad placement. The value is 'item_card'.

PaginationMetadata Object

Field	Type	Required	Description
`token`	string		Opaque session token identifying the cached result set. Pass this value in the next request's pagination_context.token field to retrieve additional pages without triggering a new auction.
`offset`	integer		The page position returned in this response, starting at 1. To advance to the next page, increment this value by 1 in the following request's pagination_context.offset.

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​

PaginationContext Object​

Request examples​

Pagination​

Pagination behavior​

Response​

SponsoredProduct Object​

PaginationMetadata Object​

Response examples​