Widgets
Page Widgets
Guide

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

UI NamePermissionParameterDescription
Contentmodifystore_v2_contentView 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

ParameterRequiredDescription
channel_idnoThe channel ID of the subject storefront.
template_filenoThe 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_idnoIf 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/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.

PropertyRequiredDescription
channel_idyesThe channel ID of the target storefront.
template_filenoThe name of the target theme template file.
entity_idno

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?