# BigCommerce Widget: What It Is and How It Gets Placed

> What a BigCommerce widget is, how template, region and placement combine in the Widgets API, and how to check it shows up in your store's HTML.

URL: https://clione.ai/glossary/bigcommerce-widget/
Lang: en

"Widget" gets used for almost any box embedded in a website. Here it is one specific BigCommerce object: **the piece an app or an agency uses to put content on the pages of a [Stencil](/glossary/bigcommerce-stencil/) theme without editing the theme's files**. A banner, a block of frequently asked questions or the [structured data](/glossary/structured-data/) of a [product page](/glossary/product-page/) can arrive that way. For a store it matters for a practical reason: if the widget has no region to land in, or its placement is inactive, the content exists in the control panel and does not exist on the page.

## How it works

The Widgets API is for creating units of content and placing them programmatically on specific pages of a BigCommerce store. That content can be HTML, CSS and JavaScript, and it is configured with Handlebars variables.[^bc-widgets] The documentation breaks it into five concepts:[^bc-widgets]

| Concept         | What it is                                                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Widget template | Handlebars HTML that defines the widget's structure. It is reused to create several widgets                                                                  |
| Widget          | A configuration plus the identifier (UUID) of its template                                                                                                   |
| Configuration   | The JSON with the content the template renders, up to 64 KB                                                                                                  |
| Region          | A slot declared in the Stencil theme's files with `{{{region name="..."}}}`. Those ending in `--global` are shown across the whole site |
| Placement       | Decides which region the widget goes in and in what order                                                                                                    |

Widgets **render as part of the store's HTML**. On the page they are recognized by two attributes, `data-content-region` on the region and `data-widget-id` on the widget.[^bc-widgets]

The placement is where almost everything is decided. It is created with a `POST` request to `/v3/content/placements` and requires only two fields: `template_file`, the page template it points to, and `widget_uuid`, the widget.[^bc-placement] The rest fine-tune it:[^bc-placement]

- `entity_id` limits the placement to one specific page: the product ID on a product page, the category ID on a category. The home page does not accept it. According to the documentation, the identifier can belong to a product, a brand, a category or a page.[^bc-widgets]
- `region` and `sort_order` say which region it goes in and in what position, if there are several widgets in the same one.
- `channel_id` picks the channel; if you do not give one, it uses the first channel created in the store.
- `status` can be `active` or `inactive`, and **it defaults to `inactive`**.

Placements with a region show up in Page Builder; those without a region need the layout to be configured directly.[^bc-placement] The possible page templates include `pages/product`, `pages/category` and `pages/home`, among others.[^bc-placements-course]

And there are per-store limits: 100,000 widgets, 1,000 custom templates per channel and 5,000 in total, **75 placements per page template** and 10,000 placements in total.[^bc-widgets] If you create one placement per product, on a large catalog you hit that limit soon.

## In a store

A **fictitious example**: a widget with a tripod's [JSON-LD](/glossary/json-ld/), placed only on its product page. The placement would be requested like this (the region name depends on the theme; this one is made up):

```json
{
  "widget_uuid": "00000000-0000-4000-8000-000000000001",
  "template_file": "pages/product",
  "entity_id": "112",
  "region": "product_bottom",
  "sort_order": 1,
  "status": "active"
}
```

And in the HTML of product page 112 something like this would appear (simplified):

```html
<div data-content-region="product_bottom">
  <div data-widget-id="00000000-0000-4000-8000-000000000001">
    <script type="application/ld+json">
      { "@context": "https://schema.org", ... }
    </script>
  </div>
</div>
```

That the markup ends up in the body and not in the head is not a problem for Google: JSON-LD goes in a `<script>` tag **inside the `<head>` or the `<body>`**, and Google also processes it when content management widgets inject it.[^google-structured-data] Clione uses this same path: on BigCommerce, its structured data graph is published with the Widget API and rendered on the server.


**Creating the widget is not publishing it.** A widget with no placement does not show on any page, and a placement created without `status` stays `inactive`, which is the default.[^bc-placement] On top of that, the region has to exist in the files of the theme the store uses, because regions are slots the theme declares.[^bc-widgets] Before hunting for the fault in the template, check those two things.


## How to check it

1. **Look up the theme's regions** with the Widgets API's regions endpoint, for the page template you care about. If the region your placement uses is not on the list, the widget has nowhere to land.[^bc-widgets]
2. **Review the placement**: `status` set to `active`, the right `template_file`, the `entity_id` of the product or category you expect and the right channel.[^bc-placement]
3. **Open the page and its source code** (Ctrl+U in Chrome) and search for `data-widget-id`. If it does not appear, the problem is in the placement or the region, not in the template.[^bc-widgets]
4. **If the widget publishes structured data**, run the URL through the [Rich Results Test](/glossary/rich-results-test/) or a [schema markup validator](/glossary/schema-markup-validator/).
5. **Count your placements** per page template before scaling to the whole catalog: the limit is 75 per template.[^bc-widgets]

## Related concept: Shopify app embed

The closest equivalent on Shopify is the [Shopify app embed](/glossary/shopify-app-embed/). Both put code in the store without editing the theme, but they are placed differently. Shopify inserts an app embed **before the closing `</head>` or `</body>`**, depending on the target the block declares, and the merchant turns it on in the theme editor; after the app is installed it starts off.[^shopify-tae-config] A BigCommerce widget, by contrast, goes in the region and on the page its placement says, which is created through the API, and it can be limited to a single product page with `entity_id`.[^bc-placement] In both cases, what really counts is what comes out in the page's HTML, and you check that by opening it.

The guide [from widget to published page](/guides/bigcommerce-widget-to-published-page/) follows the whole path on BigCommerce, and the [publishing by platform reading path](/learn/publishing-by-platform/) puts the rest of the terms in order.