Closed Beta ProgramsPage Widgets
Guide to the Page Widgets API (Beta)
Beta access
This API is in beta. We may introduce breaking changes without notice. We recommend implementing robust error handling if you choose to use this API in production.
By participating in this beta, you acknowledge that you are responsible for taking preventive measures to preserve and store existing data before using the Page Widgets API.
A POST request to Publish or overwrite a page deletes any and all existing data for the requested page and replaces it with data in the request payload.
During beta, the Page Widgets API supports the following actions:
- Duplicating pages
- Modifying widget content for an entire page using a single API call
- Migrating Page Widgets and layout configurations from a staging store to production store
- Moving Page Widgets from store to store or channel to channel
- Storing snapshots of Page Widgets and layout configurations
- Restoring Page Widgets and layout configurations
Concepts and limits
The Page Widgets API makes page layouts portable by dividing pages into Regions, Layouts, Dropzones, and Widgets. The following sections describe the properties and relationships of the corresponding Page Widget objects.
Regions
A Region object contains the following properties:
Layouts
Limits for Layout objects:
- per page: 150
- per channel: 10,000
A Layout object contains the following properties:
| Property | Type | Description |
|---|---|---|
layout_template_uuid | UUID string | Set by BigCommerce. Read-only. |
configuration | object | A JSON object that describes the Page Builder options menu that corresponds with the Layout. |
name | string | A human-readable label for the Layout; displays in Page Builder. |
dropzones | array | Consists of Dropzone objects. |
type | string, enum | layout |
Dropzones
A Dropzone object contains the following properties:
| Property | Type | Description |
|---|---|---|
configuration | object | A JSON object that describes the Page Builder options menu that corresponds with the Dropzone. |
widgets | array | Consists of Widget objects. |
Widgets
Limits for Widget objects:
- per page: 150
- per channel: 50,000
A Widget object contains the following properties:
| Property | Type | Description |
|---|---|---|
widget_template_uuid | UUID string | The unique identifier of the parent Widget Template; set by the store or channel where the widget template originated. |
configuration | object | A JSON object that describes the Page Builder options menu that corresponds with the Widget. |
storefront_api_query_params | string | A comma-separated list of parameters used to query the GraphQL Storefront API. Used when the parent widget template is configured to request data directly from the GraphQL Storefront API; in this case, the parent widget template has the storefront_api_query property. |
name | string | A human-readable label for the Widget. Retrievable using the Widgets API. |
description | string | A description of the Widget. Retrievable using the Widgets API. |
type | string, enum | widget |
Prerequisites
- A BigCommerce sandbox store, staging store, or trial store with the Page Widgets API enabled
- 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 the following query parameters:
| Parameter | Required | Description |
|---|---|---|
channel_id | yes | 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.
Example request: 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
Example response: Get a page snapshot
{ "data": { "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" } ] } ] }, "meta": {} }
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 regions 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. 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 productId needs to be from the target store channel.
A successful request to the Publish or overwrite a page endpoint returns a 201 Created status code.
Example Page Widgets POST API
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" } ] } ] }
