bc-widgets

BigCommerce Widgets & Script Manager

Before writing code

Fetch live docs:

1. Fetch https://docs.bigcommerce.com/developer/docs/admin/widgets-and-scripts/overview for Widget SDK
2. Web-search site:developer.bigcommerce.com scripts api for Script Manager API
3. Web-search bigcommerce page builder widgets custom for custom widget patterns

Widget System

Architecture

Widgets are reusable content components managed via API:

• Widget Template — Handlebars template defining the HTML output
• Widget — an instance of a template with specific configuration data
• Placement — positions a widget in a specific theme region on specific pages
• Page Builder — admin drag-and-drop UI that creates widgets and placements

How It Fits Together

Widget Template (Handlebars + JSON schema)
    ↓
Widget (template + configuration data)
    ↓
Placement (widget + region + page)
    ↓
Rendered on storefront

Widget Templates

Creating a Template

POST /v3/content/widget-templates:

{
  "name": "Banner with CTA",
  "storefront_api_query": "query { site { settings { storeName } } }",
  "schema": [
    {
      "type": "tab",
      "label": "Content",
      "sections": [
        {
          "label": "Banner",
          "settings": [
            {
              "type": "text",
              "label": "Heading",
              "id": "heading",
              "default": "Welcome"
            },
            {
              "type": "text",
              "label": "Button Text",
              "id": "buttonText",
              "default": "Shop Now"
            },
            {
              "type": "text",
              "label": "Button URL",
              "id": "buttonUrl",
              "default": "/shop"
            }
          ]
        }
      ]
    }
  ],
  "template": "<div class='banner'><h2>{{heading}}</h2><a href='{{buttonUrl}}'>{{buttonText}}</a></div>"
}

Schema Field Types

Type	Description
text	Text input
textarea	Multi-line text
number	Numeric input
boolean	Toggle/checkbox
select	Dropdown select
color	Color picker
imageManager	Image upload/select
productId	Product picker
categoryId	Category picker
range	Slider
alignment	Text alignment