For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
  • Overview
    • Quick Start
    • Sandboxes
    • Tools & SDKs
    • Support
  • Docs
      • Getting Started
        • Overview
        • Localization
          • Overview
          • Guide
        • Examples
        • Widget Builder
        • Scripts
    • Archive
    • Closed Beta Programs
Dev Portal
LogoLogo
On this page
  • Concepts and limits
  • Regions
  • Layouts
  • Dropzones
  • Widgets
  • Resources
  • REST Content API reference
DocsAdminWidgets & ScriptsPage Widgets

Overview: Page widgets

Was this page helpful?
Previous

Visibility

Next

Guide

Built with

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.

The page widgets feature 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

Page widgets make page layouts portable by dividing pages into regions, layouts, dropzones, and widgets. The following sections describe the properties and relationships of the page widgets objects.

Diagram of conceptual relationships in the page widgets feature

Regions

A region object contains the following properties:

PropertyTypeDescription
namestringMatches the name specified as {{{region_name="..."}}} in a theme template file.
childrenarrayConsists of layout and/or widget objects.

Layouts

Limits for layout objects: - per page: 150 - per channel: 10,000

A layout object contains the following properties:

PropertyTypeDescription
layout_template_uuidUUID stringSet by BigCommerce. Read-only.
configurationobjectA JSON object that describes the Page Builder options menu that corresponds with the layout.
namestringA human-readable label for the layout; displays in Page Builder.
dropzonesarrayConsists of dropzone objects.
typestring, enumlayout

Dropzones

Dropzones are any areas in a layout in which a widget can be dropped. A dropzone object contains the following properties:

PropertyTypeDescription
configurationobjectA JSON object that describes the Page Builder options menu that corresponds with the dropzone.
widgetsarrayConsists of widget objects.

Widgets

Limits for widget objects: - per page: 150 - per channel: 50,000

A widget object contains the following properties:

PropertyTypeDescription
widget_template_uuidUUID stringThe unique identifier of the parent widget template; set by the store or channel where the widget template originated.
configurationobjectA JSON object that describes the Page Builder options menu that corresponds with the widget.
storefront_api_query_paramsstringA 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.
namestringA human-readable label for the widget. Retrievable using either the Get a widget or the Get all widgets endpoint.
descriptionstringA description of the widget. Retrievable using either the Get a widget or the Get all widgets endpoint.
typestring, enumwidget

Resources

  • Guide to page widgets

REST Content API reference

  • Page widgets
  • Widgets