Get display placements

POST /v2/ian/dp

Retrieves display placements to display in banners on your site, such as display ads, shoppable display ads, and shoppable video ads. Specify the context in the request body.

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`	DisplayPageContext	Specific page context for the requested ads.
`placement_context`	DisplayPlacementContext	Specific display placement context for the requested ads.
`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.

DisplayPageContext Object

Field	Type	Description
`page_query`	DisplayQuery	Define one DisplayQuery object per request. This object sets the query for the page to show ads.
`filter_query`	FilterQuery	Filters to narrow the returned ads. Supports tag-based and brand-based filtering for eligible placement types. The product_category_filter_query field is not applied to display placement requests. Filters are applied independently of the page type. Your catalog inventory file must include the corresponding tags or brand IDs for filtering to take effect.
`ad_load_query`	AdLoadQuery	Controls the maximum number of ads returned in the response.

DisplayQuery Object

Field	Type	Description
`search_query`	SearchQuery	Retrieves display ads for a search results page. Only one page query option may be specified per request.
`storefront_query`	StorefrontQuery	Retrieves display ads for the storefront page. Only one page query option may be specified per request.
`product_category_query`	ProductCategoryQuery	Retrieves display ads for a product category or browse page. Only one page query option may be specified per request.
`product_detail_query`	ProductDetailQuery	Retrieves display ads for a product detail page. Only one page query option may be specified per request.
`cart_query`	CartQuery	Retrieves display ads for the cart page. Only one page query option may be specified per request.
`deals_query`	DealsQuery	Retrieves display ads for the deals page. Only one page query option may be specified per request.
`health_query`	HealthQuery	Retrieves display ads for the health page. Only one page query option may be specified per request.
`lists_query`	ListsQuery	Retrieves display ads for the lists page. Only one page query option may be specified per request.

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.

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.

ProductDetailQuery 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.
`category_ids`	Array(integer)		Product category identifiers for the request.

CartQuery 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.

DealsQuery 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.

HealthQuery 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.

ListsQuery 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.

FilterQuery Object

Field	Type	Description
`filter_tags`	FilterTags	Filters ad results by product tags. When specified, only products that match all tags in the request are returned. The object must contain a 'tags' array. Example: { "filter_tags": { "tags": ["tag1", "tag2"] } }. Not applicable to display banner (image_banner) requests.
`product_category_filter_query`	ProductCategoryFilterQuery	Filters ads by product category, returning only ads where the product matches at least one specified category ID. Applies to search, Buy It Again, and storefront placements. Not applicable to display banner, shoppable display, or shoppable video requests (ignored if specified). For product category placements and pages, specify category IDs in the page_query object instead.
`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. Not applicable to display banner requests.

FilterTags Object

Field	Type	Required	Description
`tags`	Array(string)		An array of tag strings. Only products that match all of the specified tags are returned.

ProductCategoryFilterQuery Object

Field	Type	Required	Description
`category_ids`	Array(integer)		An array of product category IDs. This field is not applicable to display placement requests. Any specified value is ignored.

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.

DisplayPlacementContext Object

Field	Type	Required	Description
`placement_kind`	DisplayKind		Define one DisplayKind object per request. This object sets the kind of placement for showing ads.

DisplayKind Object

Field	Type	Required	Description
`display_placement`	DisplayPlacement		Display placement parameters for the requested ads. `supported_format` may list `shoppable_display`, `shoppable_video`, or `image_banner` (see that field). Use `rectangle_query` to define the rectangle slot. Provide only one placement configuration per request. Shoppable formats return shoppable display or video ads; `image_banner` returns image display banner creatives for the slot.

DisplayPlacement Object

Field	Type	Required	Description
`supported_format`	Array(string)		supported formats: ['shoppable_display', 'shoppable_video', 'image_banner'].
`rectangle_query`	RectangleQuery		The query for the rectangular space that needs to be filled with a display ad.

RectangleQuery Object

Field	Type	Required	Description
`position`	string		The position of the rectangle space. This could be at the top or interleaved into middle of the page. Supported values: ['top', 'interleaved'].

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/dp \
  --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": {
      "display_placement": {
        "supported_format": [
          "string"
        ],
        "rectangle_query": {
          "position": "top"
        }
      }
    }
  },
  "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 creatives array.

Response

Field	Type	Required	Description
`creatives`	Array(Creative)		List of display creatives.
`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.

Creative Object

Field	Type	Description
`object_tracking_id`	string	A unique tracking identifier for the creative instance in the auction where it ran.
`type`	string	The type of the creative. The type sets the expected identifiers and their respected types on the actions and assets.
`assets`	Array(Asset)	List of assets associated with the creative.
`actions`	Array(Action)	List of actions associated with the creative.
`properties`	Array(CreativeProperty)	List of properties associated with the creative.

Asset Object

Field	Type	Description
`name`	string	The name of the asset. Supported values: ['brand_logo', 'hero_image', 'image_web', 'image_mobile'].
`type`	string	The type of asset, which sets constraints over the asset medium's properties. Supported values: ['image_display_banner_large', 'image_display_banner_small', 'brand_logo_promoted_aisle', 'image_promoted_aisle_hero_banner'].
`medium_properties`	Properties	Used to describe both the medium of the asset and the properties that are inherent to such a medium.

Properties Object

Field	Type	Required	Description
`image`	ImageMediumProperties		Properties of the image medium.
`video`	VideoMediumProperties		Properties of the video medium.

ImageMediumProperties Object

Field	Type	Description
`public_url`	string	Public URL that a client must use for rendering. This URL uses the https:// scheme.
`alt_text`	string	Alternative text to display in case the image fails loading.
`image_metadata`	ImageMetadata	Additional information about the image. This can be used to assist rendering, where needed.

ImageMetadata Object

Field	Type	Description
`width`	integer	Width of the image.
`height`	integer	Height of the image.
`size_bytes`	integer	Size of the image.
`content_type`	string	MIME-type of the image.

VideoMediumProperties Object

Field	Type	Required	Description
`video_url`	string		Public URL that a client must use for rendering.

Action Object

Field	Type	Description
`name`	string	The name of the action. Supported values: ['banner_click', 'main_product_group_grid_x'].
`interaction_id`	string	Unique identifier of the action instance that should be used for tracking were this rendered in a client and interacted with.
`action_properties`	ActionProperties	Describes the action associated with the creative, such as render the brand page when the user clicks the banner.

ActionProperties Object

Field	Type	Required	Description
`brand_page_click`	BrandPageClick		Click to brand page action. One of the actions in this table is returned per action property.
`item_card`	ItemCard		The action describes an item card. One of the actions in this table is returned per action property.

BrandPageClick Object

Field	Type	Required	Description
`slug`	string		Identifier for a brand page. Example: '/pepsi/superbowl-page'.

ItemCard Object

Field	Type	Description
`position`	integer	The suggested display position of the product.
`product_id`	string	Instacart product ID.
`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.

CreativeProperty Object

Field	Type	Required	Description
`name`	string		The name of the property. Supported value: ['tagline'].
`value`	string		The values of the property.

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 banner placement kind
200 Request with storefront page query and banner placement kind

{
  "creatives": [
    {
      "object_tracking_id": "urn:i-ic-v1:dcid:a/78219bd2-981d-49fb-a485-aaee5ddd8dfa",
      "type": "search_banner.v1",
      "assets": [
        {
          "type": "image_display_banner_large",
          "medium_properties": {
            "image": {
              "public_url": "https://cloudfront.net/image.jpg",
              "alt_text": "buy now",
              "image_metadata": {
                "width": 3200,
                "height": 400,
                "size_bytes": 123456,
                "content_type": "image/jpeg"
              }
            }
          }
        },
        {
          "type": "image_display_banner_small",
          "medium_properties": {
            "image": {
              "public_url": "https://cloudfront.net/image.jpg",
              "alt_text": "buy now",
              "image_metadata": {
                "width": 3200,
                "height": 400,
                "size_bytes": 123456,
                "content_type": "image/jpeg"
              }
            }
          }
        }
      ],
      "actions": [
        {
          "name": "banner_click",
          "interaction_id": "fc1f4b15-1c13-410f-bdc2-8457bbe95206",
          "action_properties": {
            "brand_page_click": {
              "slug": "/pepsi/superbowl-page"
            }
          }
        }
      ]
    }
  ]
}

{
  "creatives": [
    {
      "object_tracking_id": "urn:i-ic-v1:dcid:a/78219bd2-981d-49fb-a485-aaee5ddd8dfa",
      "type": "search_banner.v1",
      "assets": [
        {
          "type": "image_display_banner_large",
          "medium_properties": {
            "image": {
              "public_url": "https://cloudfront.net/image.jpg",
              "alt_text": "buy now",
              "image_metadata": {
                "width": 3200,
                "height": 400,
                "size_bytes": 123456,
                "content_type": "image/jpeg"
              }
            }
          }
        },
        {
          "type": "image_display_banner_small",
          "medium_properties": {
            "image": {
              "public_url": "https://cloudfront.net/image.jpg",
              "alt_text": "buy now",
              "image_metadata": {
                "width": 3200,
                "height": 400,
                "size_bytes": 123456,
                "content_type": "image/jpeg"
              }
            }
          }
        }
      ],
      "actions": [
        {
          "name": "banner_click",
          "interaction_id": "fc1f4b15-1c13-410f-bdc2-8457bbe95206",
          "action_properties": {
            "brand_page_click": {
              "slug": "/pepsi/superbowl-page"
            }
          }
        }
      ]
    }
  ]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
`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`	invalid placement kind	"the number of attributes given for placement_kind is 0"	`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​

DisplayPageContext Object​

DisplayQuery Object​

SearchQuery Object​

StorefrontQuery Object​

ProductCategoryQuery Object​

ProductDetailQuery Object​

CartQuery Object​

DealsQuery Object​

HealthQuery Object​

ListsQuery Object​

FilterQuery Object​

FilterTags Object​

ProductCategoryFilterQuery Object​

AdLoadQuery Object​

DisplayPlacementContext Object​

DisplayKind Object​

DisplayPlacement Object​

RectangleQuery Object​

SessionContext Object​

StoreContext Object​

PaginationContext Object​

Request examples​

Pagination​

Pagination behavior​

Response​

Creative Object​

Asset Object​

Properties Object​

ImageMediumProperties Object​

ImageMetadata Object​

VideoMediumProperties Object​

Action Object​

ActionProperties Object​

BrandPageClick Object​

ItemCard Object​

CreativeProperty Object​

PaginationMetadata Object​

Response examples​