Guide to page widgets
⚠️
A POST request to Publish or overwrite a page deletes any and all existing data for the requested page and replaces it with the data in the request payload.
Prerequisites
- A store-level or app-level API Account with OAuth scopes that include the following. Pass the API account's access token as the value of the
X-Auth-Tokenheader. For more information, see Authentication and Example Requests.
| UI Name | Permission | Parameter | Description |
|---|---|---|---|
| Content | modify | store_v2_content | View and modify store content |
Get a page snapshot
To download a snapshot of a single page's regions, layouts, dropzones, and widgets, use the Get a page snapshot endpoint.
You can use a number of query parameters to describe the page features you want to retrieve. See more descriptions, defaults, and examples in the REST Content API reference
| Parameter | Required | Description |
|---|---|---|
channel_id | no | The channel ID of the subject storefront. |
template_file | no | The name of the subject theme template file. If you want a snapshot of global regions in a storefront, do not include a value for the template_file query parameter. |
entity_id | no | If you want a snapshot of global regions in a storefront, do not include a value for the entity_id query parameter. |
Some template files don't have an entity ID. For example, the pages/home
template file doesn't have an entity ID.
Get a page snapshot
GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/content/page-widgets?channel_id={{CHANNEL_ID}}&template_file={{TEMPLATE_FILE}}&entity_id={{ENTITY_ID}}
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/jsonPublish or overwrite a page
To publish or overwrite the content of a page, use the Publish or overwrite a page endpoint. One way to prepare a publication payload is to Get a snapshot of a page that you want to copy or modify. The snapshot contains region data that you can use as a request body payload for the Publish or overwrite a page endpoint.
⚠️
When starting with a snapshot from another storefront, make sure to replace any store or channel-specific data in the request body.
| Property | Required | Description |
|---|---|---|
channel_id | yes | The channel ID of the target storefront. |
template_file | no | The name of the target theme template file. |
entity_id | no |
Ensure that you have the widget_template_uuid of each widget you want to publish. The widget_template_uuid is unique to each store channel. If you are publishing to a different store or channel than you got the page snapshot from, you must re-register any widget templates you use in the target store channel using the Create a widget template endpoint. In your payload for the Publish or overwrite a page endpoint, substitute the correct widget_template_uuid for the target store or channel.
In addition, some widgets might require store or channel-specific data in the configuration or storefront_api_query_params objects. Notice productId in configuration or storefront_api_query_params in the following example. In this case, the correct productId corresponds with the desired product on the target store and channel.
A successful request to the Publish or overwrite a page endpoint returns a 201 Created status code, and does not return a response body.
Publish or overwrite a page
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/content/page-widgets
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json
{
"channel_id": 1,
"template_file": "pages/page",
"entity_id": "5",
"regions": [
{
"name": "home_below_menu",
"children": [
{
"widget_template_uuid": "d181ebd5-f42c-4f96-8f9d-c605023f5cb6",
"configuration": {
"title": "Hero Banner Title",
"subtitle": "Add a description for this hero banner. This is a great place to highlight a promotion.",
"buttonText": "Shop now",
"contentAlignment": {
"horizontal": "left"
},
"containerHeight": "small",
"backgroundType": "image",
"backgroundColor": "#444444",
"imageUrl": {
"src": "https://images.unsplash.com/photo-1533038590840-1cde6e668a91?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=2000&q=100",
"type": "IMAGE_MANAGER"
},
"imageFit": "fill",
"imageParallax": "off",
"imageAlignment": {
"horizontal": "center",
"vertical": "middle"
},
"imageOpacity": 100,
"titleVisible": "show",
"titleStyle": "default",
"titleFontFamily": "inherit",
"titleFontWeight": "400",
"titleFontSize": {
"value": 36,
"type": "px"
},
"descriptionVisible": "show",
"descriptionStyle": "default",
"descriptionFontFamily": "inherit",
"descriptionFontWeight": "400",
"descriptionFontSize": {
"value": 21,
"type": "px"
},
"textColor": "#444444",
"mobileTextColor": "#444444",
"buttonVisible": "show",
"buttonFont": "default",
"buttonFontFamily": "inherit",
"buttonStyle": "round",
"buttonColor": "#444444",
"mobileButtonColor": "#444444",
"buttonTextColor": "rgba(255,255,255,1)",
"mobileButtonTextColor": "rgba(255,255,255,1)"
},
"storefront_api_query_params": {},
"name": "Hero Banner",
"description": "",
"type": "widget"
}
]
},
{
"name": "header_bottom",
"children": [
{
"layout_template_uuid": "7d42d0b1-1152-4ce3-a6c1-3709f786f295",
"configuration": {
"columnWeights": [
"33.333333%",
"33.333333%",
"33.333333%"
],
"layoutBackgroundColor": "rgba(0,0,0,0)",
"layoutBackgroundImageAlignment": {
"horizontal": "center",
"vertical": "middle"
},
"layoutBackgroundImageFit": "fill",
"layoutBackgroundImageOpacity": 100,
"layoutBackgroundImageUrl": "",
"layoutBorderColor": "#333333",
"layoutBorderStyle": "solid",
"layoutBorderThickness": 0,
"layoutHeight": "",
"layoutMargin": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "0"
},
"right": {
"type": "px",
"value": "0"
},
"top": {
"type": "px",
"value": "0"
}
},
"layoutPadding": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "0"
},
"right": {
"type": "px",
"value": "0"
},
"top": {
"type": "px",
"value": "0"
}
},
"numberOfDropzones": 3,
"layoutBackgroundType": "",
"layoutZIndex": "auto",
"name": "Layout"
},
"name": "Layout",
"dropzones": [
{
"configuration": {
"dropzoneBackgroundColor": "rgba(0,0,0,0)",
"dropzoneBackgroundImageAlignment": {
"horizontal": "center",
"vertical": "middle"
},
"dropzoneBackgroundImageFit": "fill",
"dropzoneBackgroundImageOpacity": 100,
"dropzoneBackgroundImageUrl": "",
"dropzoneBorderColor": "#333333",
"dropzoneBorderStyle": "solid",
"dropzoneBorderThickness": 0,
"dropzoneHeight": "",
"dropzoneJustifyContent": "center",
"dropzoneMargin": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "0"
},
"right": {
"type": "px",
"value": "0"
},
"top": {
"type": "px",
"value": "0"
}
},
"dropzonePadding": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "10.5"
},
"right": {
"type": "px",
"value": "10.5"
},
"top": {
"type": "px",
"value": "0"
}
},
"dropzoneZIndex": "auto",
"dropzoneBackgroundType": ""
},
"widgets": [
{
"widget_template_uuid": "e59c1412-2d85-4f18-ab4b-8a55412d945c",
"configuration": {
"productCardContentAlignment": {
"horizontal": "center"
},
"productImage": {
"visibility": "show",
"imageFit": "fill"
},
"brand": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"productName": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"price": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"productRating": {
"visibility": "hide",
"starColorFilled": "#3C64F4",
"starColorEmpty": "#ECEEF5",
"reviewsColor": "#8C93AD"
},
"button": {
"visibility": "hide",
"shape": "round",
"buttonColor": "rgba(68,68,68,1)",
"textStyle": "default",
"buttonTextColor": "rgba(255,255,255,1)",
"buttonActionType": "addToCart"
},
"productId": "77"
},
"storefront_api_query_params": {
"productId": 77
},
"name": "Product",
"description": "",
"type": "widget"
}
]
},
{
"configuration": {
"dropzoneBackgroundColor": "rgba(0,0,0,0)",
"dropzoneBackgroundImageAlignment": {
"horizontal": "center",
"vertical": "middle"
},
"dropzoneBackgroundImageFit": "fill",
"dropzoneBackgroundImageOpacity": 100,
"dropzoneBackgroundImageUrl": "",
"dropzoneBorderColor": "#333333",
"dropzoneBorderStyle": "solid",
"dropzoneBorderThickness": 0,
"dropzoneHeight": "",
"dropzoneJustifyContent": "center",
"dropzoneMargin": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "0"
},
"right": {
"type": "px",
"value": "0"
},
"top": {
"type": "px",
"value": "0"
}
},
"dropzonePadding": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "10.5"
},
"right": {
"type": "px",
"value": "10.5"
},
"top": {
"type": "px",
"value": "0"
}
},
"dropzoneZIndex": "auto",
"dropzoneBackgroundType": ""
},
"widgets": [
{
"widget_template_uuid": "e59c1412-2d85-4f18-ab4b-8a55412d945c",
"configuration": {
"productCardContentAlignment": {
"horizontal": "center"
},
"productImage": {
"visibility": "show",
"imageFit": "fill"
},
"brand": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"productName": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"price": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"productRating": {
"visibility": "hide",
"starColorFilled": "#3C64F4",
"starColorEmpty": "#ECEEF5",
"reviewsColor": "#8C93AD"
},
"button": {
"visibility": "hide",
"shape": "round",
"buttonColor": "rgba(68,68,68,1)",
"textStyle": "default",
"buttonTextColor": "rgba(255,255,255,1)",
"buttonActionType": "addToCart"
},
"productId": "80"
},
"storefront_api_query_params": {
"productId": 80
},
"name": "Product",
"description": "",
"type": "widget"
}
]
},
{
"configuration": {
"dropzoneBackgroundColor": "rgba(0,0,0,0)",
"dropzoneBackgroundImageAlignment": {
"horizontal": "center",
"vertical": "middle"
},
"dropzoneBackgroundImageFit": "fill",
"dropzoneBackgroundImageOpacity": 100,
"dropzoneBackgroundImageUrl": "",
"dropzoneBorderColor": "#333333",
"dropzoneBorderStyle": "solid",
"dropzoneBorderThickness": 0,
"dropzoneHeight": "",
"dropzoneJustifyContent": "center",
"dropzoneMargin": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "0"
},
"right": {
"type": "px",
"value": "0"
},
"top": {
"type": "px",
"value": "0"
}
},
"dropzonePadding": {
"bottom": {
"type": "px",
"value": "0"
},
"left": {
"type": "px",
"value": "10.5"
},
"right": {
"type": "px",
"value": "10.5"
},
"top": {
"type": "px",
"value": "0"
}
},
"dropzoneZIndex": "auto",
"dropzoneBackgroundType": ""
},
"widgets": [
{
"widget_template_uuid": "e59c1412-2d85-4f18-ab4b-8a55412d945c",
"configuration": {
"productCardContentAlignment": {
"horizontal": "center"
},
"productImage": {
"visibility": "show",
"imageFit": "fill"
},
"brand": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"productName": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"price": {
"visibility": "show",
"textStyle": "default",
"color": "#444444"
},
"productRating": {
"visibility": "hide",
"starColorFilled": "#3C64F4",
"starColorEmpty": "#ECEEF5",
"reviewsColor": "#8C93AD"
},
"button": {
"visibility": "hide",
"shape": "round",
"buttonColor": "rgba(68,68,68,1)",
"textStyle": "default",
"buttonTextColor": "rgba(255,255,255,1)",
"buttonActionType": "addToCart"
},
"productId": "93"
},
"storefront_api_query_params": {
"productId": 93
},
"name": "Product",
"description": "",
"type": "widget"
}
]
}
],
"type": "layout"
}
]
}
]
}Resources
REST Content API reference
Did you find what you were looking for?