Thanks for being patient while we implement your feedback to improve the developer experience.

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

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

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

    • 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"
        },
        "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": {
        "channel_id": 1,
        "client_rerender": false,
        "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}}",
        "template_engine": "handlebars_v3",
        "uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
      }
    }
  },
  "meta": {}
}

    Get All Placements

    GET /content/placements

    Request

    Returns a list of Placements.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • 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 - string

      A comma-separated list of channel ids to filter the results by.

    • site_id:in in query - string

      A comma-separated list of site IDs to filter the results by.

    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: xxxxxxxxxxxxxxxxx'

    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": {
          "_": {
            "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": {
          "channel_id": 1,
          "client_rerender": false,
          "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}}",
          "template_engine": "handlebars_v3",
          "uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "count": 1,
      "current_page": 1,
      "per_page": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}

    Get a Placement

    GET /content/placements/{uuid}

    Request

    Returns a single Placement.

    Authentication

    • X-Auth-Token in header - required

    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: xxxxxxxxxxxxxxxxx'

    Response

    Body

    object | application/json

    • data

    • 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"
        },
        "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": {
        "channel_id": 1,
        "client_rerender": false,
        "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}}",
        "template_engine": "handlebars_v3",
        "uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
      }
    }
  },
  "meta": {}
}

    Update a Placement

    PUT /content/placements/{uuid}

    Request

    Updates a Placement.

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • Content-Type in header with default of application/json - string - required

      The MIME type of the request body.

    Body

    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

      • 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"
        },
        "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": {
        "channel_id": 1,
        "client_rerender": false,
        "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}}",
        "template_engine": "handlebars_v3",
        "uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
      }
    }
  },
  "meta": {}
}

      Delete a Placement

      DELETE /content/placements/{uuid}

      Request

      Deletes a Placement.

      Authentication

      • X-Auth-Token in header - required

      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: xxxxxxxxxxxxxxxxx'

      Response

      An empty response.