Guide to page widgets
This page is for Developer.
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.
Request
Response
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/json
Publish 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.
Request
Response
Publish or overwrite a page
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/content/page-widgetsX-Auth-Token: {{ACCESS_TOKEN}}Accept: application/jsonContent-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"}]}]}