Placement

Create a Placement

POST /content/placements

Request

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-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
  • widget_uuid
    string
    required

    A widget identifier.
  • template_file
    string
    required

    The template file that you would like to target.
  • channel_id
    integer

    The id of the channel on which to create this placement. Defaults to the first channel created on the store.
    Example: 1
  • entity_id
    string

    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.
  • sort_order
    integer

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

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

    Sets the placement as either inactive or active.

    Allowed: inactive | active

    Default: inactive

example

{
"widget_uuid": "string",
"template_file": "string",
"channel_id": 1,
"entity_id": "string",
"sort_order": 0,
"region": "string",
"status": "inactive"
}

Response

Body

object | application/json
  • data
    object

  • meta
    object

    Response metadata.

response

{
"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",
"storefront_api_query_params": {},
"uuid": "1f05183e-dfa4-4583-af28-250b47e177b2",
"version_uuid": "c863f77b-e5b4-4462-a9ed-2aff9005140e",
"widget_configuration": {
"_": {
"id": "1f05183e-dfa4-4583-af28-250b47e177b2"

Get All Placements

GET /content/placements

Request

Returns a list of Placements.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • page in query - integer

    Specifies the page number in a limited (paginated) list of products.

  • limit in query - integer

    Controls the number of items per page in a limited (paginated) list of products.

  • widget_template_kind in query - string
    The kind of widget template.
  • template_file in query - string
    The template file, for example: pages/home.
  • widget_uuid in query - string
    The identifier for a specific widget.
  • widget_template_uuid in query - string
    The identifier for a specific widget template.
  • channel_id:in in query - array
    A comma-separated list of channel ids to filter the results by.
    Type: array[integer]
  • site_id:in in query - array
    A comma-separated list of site IDs to filter the results by.
    Type: array[integer]

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/placements' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

response

{
"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",
"storefront_api_query_params": {},
"uuid": "1f05183e-dfa4-4583-af28-250b47e177b2",
"version_uuid": "c863f77b-e5b4-4462-a9ed-2aff9005140e",
"widget_configuration": {

Get a Placement

GET /content/placements/{uuid}

Request

Returns a single Placement.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • uuid in path - string
    required
    The identifier for a specific placement.

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/placements/[uuid]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json
  • data
    object

  • meta
    object

    Response metadata.

response

{
"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",
"storefront_api_query_params": {},
"uuid": "1f05183e-dfa4-4583-af28-250b47e177b2",
"version_uuid": "c863f77b-e5b4-4462-a9ed-2aff9005140e",
"widget_configuration": {
"_": {
"id": "1f05183e-dfa4-4583-af28-250b47e177b2"

Update a Placement

PUT /content/placements/{uuid}

Request

Updates a Placement.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • uuid in path - string
    required
    The identifier for a specific placement.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json
  • template_file
    string

    The template file that you would like to target.
  • widget_uuid
    string

    A widget identifier.
  • channel_id
    integer

    The ID of the channel on which this placement exists.
  • entity_id
    string

    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.
  • sort_order
    integer

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

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

    Sets the placement as either inactive or active.

    Allowed: inactive | active

    Default: inactive

example

{
"template_file": "string",
"widget_uuid": "string",
"channel_id": 0,
"entity_id": "string",
"sort_order": 0,
"region": "string",
"status": "inactive"
}

Response

Body

object | application/json
  • data
    object

  • meta
    object

    Response metadata.

response

{
"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",
"storefront_api_query_params": {},
"uuid": "1f05183e-dfa4-4583-af28-250b47e177b2",
"version_uuid": "c863f77b-e5b4-4462-a9ed-2aff9005140e",
"widget_configuration": {
"_": {
"id": "1f05183e-dfa4-4583-af28-250b47e177b2"

Delete a Placement

DELETE /content/placements/{uuid}

Request

Deletes a Placement.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • uuid in path - string
    required
    The identifier for a specific placement.

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/placements/[uuid]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

An empty response.
Did you find what you were looking for?