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.

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

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

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		Specify only one of the options described in this table. This option serves shoppable display ads, which include shoppable video or shoppable display.

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.

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

Response

Field	Type	Required	Description
`creatives`	Array(Creative)		List of display creatives.

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.

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​

Request examples​

Response​

Creative Object​

Asset Object​

Properties Object​

ImageMediumProperties Object​

ImageMetadata Object​

VideoMediumProperties Object​

Action Object​

ActionProperties Object​

BrandPageClick Object​

ItemCard Object​

CreativeProperty Object​

Response examples​