Get a brand page block

POST /v2/ian/bp_block

Retrieves a block of content to display within a brand page. Content can be anything the advertiser wants to display on the page, such as additional banners or lists of products. Send one block_versioned_id per request in the order in which the ids appeared in the ordered_versioned_block_ids array returned by the Get a brand page endpoint.

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
slug	string		The slug of brand page.
page_view_id	string		Identifier associated with the page view. Must be a UUID (Universal Unique Identifier).
block_versioned_id	BlockVersionedId		Versioned identifier of the block.
session_context	SessionContext		Context related to user session.
store_context	StoreContext		Context related to the selected store.

BlockVersionedId Object

Field	Type	Required	Description
type	string		Type of the brand page block.
versioned_identifier	VersionedId		Versioned identifier of the block.

VersionedId Object

Field	Type	Required	Description
gid	string		Unique ID of the entity.
version	integer		Version of the entity.

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

curl --request POST \
  --url https://connect-ian.instacart.com/v2/ian/bp_block \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Retailer-Id: string' \
  --data '{
  "slug": "string",
  "page_view_id": "string",
  "block_versioned_id": {
    "type": "HERO_BANNER",
    "versioned_identifier": {
      "gid": "string",
      "version": 1
    }
  },
  "session_context": {
    "user_id": "string",
    "user_ip": "string",
    "user_agent": "string",
    "test_only": true
  },
  "store_context": {
    "location_code": "string"
  }
}'

Java

HttpResponse<String> response = Unirest.post("https://connect-ian.instacart.com/v2/ian/bp_block")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .header("X-Retailer-Id", "string")
  .body("{\n  \"slug\": \"string\",\n  \"page_view_id\": \"string\",\n  \"block_versioned_id\": {\n    \"type\": \"HERO_BANNER\",\n    \"versioned_identifier\": {\n      \"gid\": \"string\",\n      \"version\": 1\n    }\n  },\n  \"session_context\": {\n    \"user_id\": \"string\",\n    \"user_ip\": \"string\",\n    \"user_agent\": \"string\",\n    \"test_only\": true\n  },\n  \"store_context\": {\n    \"location_code\": \"string\"\n  }\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect-ian.instacart.com")

payload = "{\n  \"slug\": \"string\",\n  \"page_view_id\": \"string\",\n  \"block_versioned_id\": {\n    \"type\": \"HERO_BANNER\",\n    \"versioned_identifier\": {\n      \"gid\": \"string\",\n      \"version\": 1\n    }\n  },\n  \"session_context\": {\n    \"user_id\": \"string\",\n    \"user_ip\": \"string\",\n    \"user_agent\": \"string\",\n    \"test_only\": true\n  },\n  \"store_context\": {\n    \"location_code\": \"string\"\n  }\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>",
    'X-Retailer-Id': "string"
}

conn.request("POST", "/v2/ian/bp_block", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect-ian.instacart.com/v2/ian/bp_block"

	payload := strings.NewReader("{\n  \"slug\": \"string\",\n  \"page_view_id\": \"string\",\n  \"block_versioned_id\": {\n    \"type\": \"HERO_BANNER\",\n    \"versioned_identifier\": {\n      \"gid\": \"string\",\n      \"version\": 1\n    }\n  },\n  \"session_context\": {\n    \"user_id\": \"string\",\n    \"user_ip\": \"string\",\n    \"user_agent\": \"string\",\n    \"test_only\": true\n  },\n  \"store_context\": {\n    \"location_code\": \"string\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Retailer-Id", "string")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
brand_page_block	Block		Content for brand page block.

Block Object

Field	Type	Required	Description
banner	Banner		Brand page banner block. May be a section banner or an image story banner with title and text. One of the blocks in this table is returned per brand page block.
item_list	ItemList		Brand page item list block. May be a standard item list or a spotlight item list with included spotlight item images. One of the blocks in this table is returned per brand page block.

Banner Object

Field	Type	Required	Description
title	string		The title of the brand page banner. Only applicable for image story banner.
text	string		The text of the brand page banner. Only applicable for image story banner.
desktop_image	ImageMediumProperties		The desktop banner image.
mobile_image	ImageMediumProperties		The mobile banner image.

ImageMediumProperties Object

Field	Type	Required	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	Required	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.

ItemList Object

Field	Type	Required	Description
title	string		The title of the item list.
product_ids	Array(integer)		The product ids of the item list.
rrcs	Array(string)		The rrcs of the item list.
upcs	Array(string)		The UPCs of the item list.
spotlight_items	Array(SpotlightItem)		Only included for spotlight item lists, which will have optional advertiser-provided images.

SpotlightItem Object

Field	Type	Required	Description
product_id	integer		The product ID of the spotlight item.
rrc	string		Retailer reference code (RRC) of the spotlight item.
upc	string		Universal product code (UPC) of the spotlight item.
desktop_image	ImageMediumProperties		Optional spotlight item image used for desktop. If an image is not returned, fall back to using the default image instead.
mobile_image	ImageMediumProperties		Optional spotlight item image used for mobile. If an image is not returned, fall back to using the default image instead.

Response examples

200 Success

200 Request for banner block

{
  "brand_page_block": {
    "banner": {
      "title": "mock title!",
      "text": "mock text",
      "desktop_image": {
        "public_url": "https://display.instacart.dev/cdn-cgi/image.png",
        "alt_text": "Awesome alt text!"
      }
    }
  }
}

200 Request for item list block

{
  "brand_page_block": {
    "item_list": {
      "title": "mock title!",
      "product_ids": [
        1234
      ],
      "rrcs": [
        "1234"
      ],
      "upcs": [
        "123456789012"
      ],
      "spotlight_items": []
    }
  }
}

200 Request for item list spotlight block

{
  "brand_page_block": {
    "item_list": {
      "title": "mock title!",
      "product_ids": [
        1234
      ],
      "rrcs": [
        "1234"
      ],
      "upcs": [
        "123456789012"
      ],
      "spotlight_items": [
        {
          "product_id": 1234,
          "rrc": "1234",
          "upc": "123456789012",
          "desktop_image": {
            "public_url": "https://display.instacart.dev/cdn-cgi/image.png",
            "alt_text": "Awesome alt text!"
          }
        }
      ]
    }
  }
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Request with invalid block type	"is not included in the list"	1001	{"key":"block_versioned_id.type"}
400	Missing slug	"can't be blank"	1001	{"key":"slug"}
400	Missing page view id	"can't be blank"	1001	{"key":"page_view_id"}
400	Invalid page view ID	"must be a UUID or 'None'"	1001	{"key":"page_view_id"}
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"}