Guide to the Page Widgets API (Beta)
Guide to the Page Widgets API (Beta)
Guide to the Page Widgets API (Beta)
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:
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.
A Region object contains the following properties:
Limits for Layout objects:
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 |
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. |
Limits for Widget objects:
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 |
X-Auth-Token header. For more information, see Authentication and Example Requests.| UI Name | Permission | Parameter | Description |
|---|---|---|---|
| Content | modify | store_v2_content | View and modify store content |
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.
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
{ "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": {} }
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.
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" } ] } ] }