Placement
Create a Placement
POST https://api.bigcommerce.com/stores/{store_hash}/v3/content/placementsRequest
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 - stringrequiredThe MIME type of the response body.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
Body
object | application/json
template_filestring
requiredThe template file that you would like to target.channel_idinteger
The id of the channel on which to create this placement. Defaults to the first channel created on the store.Example: 1entity_idstring
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 supportentity_id
.sort_orderinteger
The sort order to control the position of a content widget in a region.regionstring
The name of the region in which to insert content widgets.statusstring
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
dataobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/content/placementsRequest
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 - stringrequiredThe 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 - stringThe kind of widget template.
- template_file in query - stringThe template file, for example:
pages/home
. - widget_uuid in query - stringThe identifier for a specific widget.
- widget_template_uuid in query - stringThe identifier for a specific widget template.
- channel_id:in in query - arrayA comma-separated list of channel ids to filter the results by.Type: array[integer]
- site_id:in in query - arrayA 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
dataarray[object]
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 https://api.bigcommerce.com/stores/{store_hash}/v3/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 - stringrequiredThe MIME type of the response body.
- uuid in path - stringrequiredThe 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
dataobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/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 - stringrequiredThe MIME type of the response body.
- uuid in path - stringrequiredThe identifier for a specific placement.
- Content-Type in header with default of application/json - stringrequiredThe MIME type of the request body.
Body
object | application/json
template_filestring
The template file that you would like to target.channel_idinteger
The ID of the channel on which this placement exists.entity_idstring
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 supportentity_id
.sort_orderinteger
The sort order to control the position of a content widget in a region.regionstring
The name of the region in which to insert content widgets.statusstring
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
dataobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/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 - stringrequiredThe MIME type of the response body.
- uuid in path - stringrequiredThe 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?