Create Placement

POST

https://api.bigcommerce.com/stores/:store_hash/v3/content/placements

POST

/stores/:store_hash/v3/content/placements

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/content/placements \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "template_file": "string",
  "widget_uuid": "string"
}'

{
  "data": {
    "channel_id": 1,
    "date_created": "2020-12-21T20:43:16.796Z",
    "date_modified": "2020-12-21T20:43:16.796Z",
    "entity_id": "21",
    "region": "category_header_banner",
    "sort_order": 1,
    "status": "active",
    "template_file": "pages/category",
    "uuid": "89eac5b3-91d7-48e5-92e7-ff53ecf07f8c",
    "widget": {
      "channel_id": 1,
      "date_created": "2020-12-21T19:54:16.406Z",
      "date_modified": "2020-12-21T20:40:45.173Z",
      "description": "",
      "name": "Header Images",
      "uuid": "1f05183e-dfa4-4583-af28-250b47e177b2",
      "version_uuid": "c863f77b-e5b4-4462-a9ed-2aff9005140e",
      "widget_configuration": {
        "_": {
          "id": "1f05183e-dfa4-4583-af28-250b47e177b2"
        },
        "images": [
          {
            "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on"
          },
          {
            "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/500x659/products/85/282/livingwithplants_grande__26452.1456436666.jpg?c=2&imbypass=on"
          },
          {
            "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on"
          }
        ]
      },
      "widget_template": {
        "current_version_uuid": "c863f77b-e5b4-4462-a9ed-2aff9005140e",
        "date_created": "2020-12-21T19:49:29.110Z",
        "date_modified": "2020-12-21T19:49:29.110Z",
        "icon_name": "default",
        "kind": "custom",
        "name": "Header Images",
        "schema": [],
        "storefront_api_query": "",
        "template": "{{#each images}}{{/each}}",
        "uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6",
        "channel_id": 1,
        "client_rerender": false,
        "template_engine": "handlebars_v3"
      },
      "storefront_api_query_params": {}
    }
  },
  "meta": {}
}

Creates a Placement.

Template Files

To view the list of values accepted by the template_file property, including custom templates, see Placements.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Content	modify	`store_v2_content`
Content	read-only	`store_v2_content_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

Path parameters

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

This endpoint expects an object.

template_filestringRequired

The template file that you would like to target.

widget_uuidstringRequired

A widget identifier.

channel_idintegerOptional

The id of the channel on which to create this placement. Defaults to the first channel created on the store.

entity_idstringOptional

The identifier of a page you would like to target. For product pages, choose product ID. For category pages, choose category ID. Home page does not support entity_id.

regionstringOptional

The name of the region in which to insert content widgets.

sort_orderintegerOptional

The sort order to control the position of a content widget in a region.

statusenumOptionalDefaults to inactive

Sets the placement as either inactive or active.

Allowed values:

Response

The requested widget placement.

dataobjectOptional

metaobjectOptional

Response metadata.

Errors

422

Unprocessable Entity Error