The Widgets API: New ways to Insert Custom Content in BigCommerce Storefronts

We’re excited to announce that the Widgets API is now available, unlocking the ability to programmatically inject custom content via HTML, JS, and CSS into Stencil templates. This enables developers to build apps that create richer e-commerce experiences on top of BigCommerce storefronts. The Widgets API lays the groundwork for future tools that will give merchants more control over their storefronts than ever before, without editing code, even opening the door to creating new workflows to manage and publish content in BigCommerce stores.

Notably, widgets separate content from its structure, allowing developers to reuse widget templates with variable content. You can place widgets on all pages of a particular type, e.g. all category pages, or you can place widgets on specific individual pages.

Widget API Concepts

The Widgets API introduces a number of new features that are designed to give you granular control over the positioning and appearance of your content.

Let’s run through a few key concepts to help you get the most out of the Widgets API:

Widgets

Widgets are the base unit of content injected into template files by the Widgets API. A widget is made up of a widget template, which defines its structure, and a widget configuration, which defines the widget’s content.

Regions

Regions are drop zones that mark the locations where widgets can be placed in Stencil theme files. Regions are defined by the region handlebars expression:

{{{region name="…"}}}

Although regions can be manually added to theme files, with the release of the Widgets API, we are working with theme authors so all Stencil themes include pre-defined regions where developers can inject widget content.

Placements

Placements tell the Widgets API which page and region a widget should be assigned to. A placement can also define a sort order, which determines the order to display multiple widgets within a single region.

You may wish to determine a widget’s positioning not just by region, but also in relation to other widgets. In that case, you can create a widget placement without specifying a region and then include the widget placement within a layout.

Layouts

Layouts allow you to group multiple widget placements together and style those placements in relation to one another. For example, you could use a layout to group multiple widget placements into a grid.

Order of Operations

Creating a fully-functioning widget requires making API calls according to a specific order of operations:

1. Widget Template
2. Widget
3. Widget Placement
4. Widget Layout (optional)

Demo

Now that we have a handle on the building blocks of the Widgets API, let’s take a look at what you can build. One exciting usage for the Widgets API is building apps that control promotional content on the storefront. You can use widgets to create a banner that lets shoppers know that all items in a particular category are on sale, or you could add a Free Shipping message below your product cards. Because this content is controlled via the API, you can create, edit, and delete a widget on the storefront, all from your app.

In this demo, we’ll show you how to create a widget that informs shoppers that all items in a particular category are on sale for 2 weeks. The widget will target the header_bottom region, which is available in Cornerstone. This will also demonstrate how you can use a page’s entity ID to assign widgets to a specific page or category.

Postman Collection

Visit the BigCommerce Developer Documentation to download the Postman spec for the Widgets API. Open Postman and navigate to File>Import, and drag and drop the spec file into the upload field. Configure your Postman environment with your X-Auth-Client and X-Auth-Token headers, and set the value for your store hash. Be sure to enable the Create Content scope when creating your credentials.

New to making BigCommerce API calls? Check out our Quick Start guide.

Create the Widget Template

Select the Create a Widget Template request from the Postman collection and send the following request body with the POST request:

{
"name": "Garden Banner",
"template": "<style>#bc-simple-text-{{_.id}} {color: {{color}};background: {{background_color}};font-size: {{font_size}};font-style: {{font_style}};font-weight: {{font_weight}};font-family: {{font_family}};text-align: {{text_align}};margin-top: {{margin_top}};margin-bottom: {{margin_bottom}};margin-left: {{margin_left}};margin-right: {{margin_right}};padding-top: {{padding_top}};padding-bottom: {{padding_bottom}};padding-left: {{padding_left}};padding-right: {{padding_right}};}</style><p id='bc-simple-text-{{_.id}}'>{{text}}</p>"
}

Copy the widget template UUID value from the response — you’ll need it for the next request.

Create the Widget

Select the Create a Widget request from the Postman collection. Send the following request body with the post request, filling in the value for widget_template_uuid with the value returned by the previous request.

{
"name": "Garden Banner",
"widget_configuration": {
"text": "All Items in the Garden Category On Sale for the Next Two Weeks!",
"_.id": "1",
"color": "#494E55",
"background_color": "#E7E7E7",
"font_size": "30px",
"font_weight": "bold",
"font_family": "'Google_Volkhov_400', sans-serif",
"text_align": "center",
"margin_right": "50px",
"margin_left": "50px",
"padding_top": "25px",
"padding_bottom": "25px"
},
"widget_template_uuid": "TODO: FILL IN WIDGET TEMPLATE ID"
}

Copy the widget UUID returned in the response — you’ll need it to create the widget placement.

Create the Placement

Select the Create a Placement request in the Postman collection and send the following request body with the POST request:

{
"widget_uuid": "TODO: FILL IN WIDGET UUID",
"template_file": "pages/category",
"status": "active",
"entity_id": "TODO: FILL IN A CATEGORY ID FROM YOUR STORE",
"sort_order": 1,
"region": "header_bottom"
}

Navigate to your category page, and you’ll see the widget displayed on the storefront.

Update a Widget

If you want to update the styling for the banner, there’s no need to create a whole new widget. We can keep the template and placement that we’ve already created and simply send an update to the widget (selected by UUID) to update the configuration.

Make note of the UUID that identifies the widget you created. In your Postman collection, locate the Update a Widget request and append your widget’s UUID to the end of the request URL:

https://api.bigcommerce.com/stores/{store_hash}/v3/content/widgets/{YOUR_WIDGET_UUID}

Send the following body with your PUT request to update the banner’s background color from gray to pink:

{
"name": "Garden Banner",
"widget_configuration": {
"text": "All Items in the Garden Category On Sale for the Next Two Weeks!",
"_.id": "1",
"color": "#494E55",
"background_color": "#EECDA7",
"font_size": "30px",
"font_weight": "bold",
"font_family": "'Google_Volkhov_400', sans-serif",
"text_align": "center",
"margin_right": "50px",
"margin_left": "50px",
"padding_top": "25px",
"padding_bottom": "25px"
},
"widget_template_uuid": "YOUR WIDGET TEMPLATE ID"
}

Deleting a Widget

When your promotion is over, you can remove the banner from the storefront by deleting the placement. One of the powerful features of widgets is the fact that they’re reusable — you can use the same widget template to create multiple widgets, and from those widgets, create multiple placements in different locations on the storefront. Deleting the placement instead of the widget itself allows you to remove the widget from one location without clearing the widget from any other locations where it may be used.

Delete the Widget Placement by sending a DELETE request to the /placements endpoint, appending the UUID for your widget placement to the URL:

https://api.bigcommerce.com/stores/{{store_hash}}/v3/content/placements/{WIDGET_PLACEMENT_UUID}

Next Steps

In just a few API calls, we’ve seen how you can programmatically create reusable widgets and inject content into the storefront. For a detailed explanation and full-length tutorial on Widgets, see our Developer Documentation. You can also browse more sample widgets in our widget code library.

Conclusion

With the Widgets API, you can create sophisticated page builder applications and merchandising functionality. Widgets support many types of content beyond simple text and images, including YouTube videos, sliders, and chat apps. As a developer, the Widgets API opens the door to building all kinds of creative and exciting solutions for BigCommerce merchants.

During the beta period, participating partners and selected merchants got a head start building Widgets-enabled integrations. We’re so excited to see the innovation that’s already happening around this release and we can’t wait to see what the developer ecosystem builds next.

We want to hear your feedback! Comment below and tell us how you plan to use the Widgets API.