The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

Accept

channel_id

A comma-separated list of channel ids to filter the results by.

channel_id:in

The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body.

Content-Type

The template file, for example: `pages/home`.

template_file

This is an optional query parameter used to fetch a specific widget template version.

version_uuid

name

widget_template_kind

The identifier for a specific widget template.

widget_template_uuid

widget_uuid

uuid

Controls the number of items per page in a limited (paginated) list of products.


limit

Use to pass in comma-separated list of widget names. Example: `/widgets?name:in=test-widget-name,header%20images`

name:in

Specifies the page number in a limited (paginated) list of products.


page

The query string associated with a widget's name and description.


query

The template file, for example: `templateFile=pages/home`.

A comma-separated list of site IDs to filter the results by.

site_id:in

This is the result of missing required fields, or of invalid data. See the response for more details.


The error title describing the particular error.


Detailed Errors

The JSON data that populates the template.

The error title describing the particular error.

error_Base

Data about the response, including pagination and collection totals.

metaCollection

Data about the response, including pagination and collection totals.


Total number of items in the collection response.


The page you are currently on within the collection.


Pagination links for the previous and next parts of the whole collection.


Link to the current page returned in the response.


Link to the next page returned in the response.


Link to the previous page returned in the response.


The amount of items returned in the collection per page, controlled by the limit parameter.


Total number of items in the result set.


The total number of pages in the collection.


pagination

The identifier of a page you would like to target. For product pages, choose product ID. For category pages, choose category ID. Home page does not support `entity_id`.

The name of the region in which to insert content widgets.

The sort order to control the position of a content widget in a region.

Sets the placement as either inactive or active.

placement_Base

The ID of the channel on which this placement exists.

The date on which this object was initially created.

The date on which this object was last updated.

The template file that you would like to target.

placement_Full

The id of the channel on which to create this placement. Defaults to the first channel created on the store.

placement_Post

placement_Put

themeRegion

The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see [Widget UI Schema](/docs/storefront/widgets/input-reference/schema). 

**Array.** Use the **array** settings type to build collections of elements within the widget. Each element in the array can contain tabs, sections, and an entire schema.

number of elements in the list to display by default.

The schema used for each element in the array.

used to display an image stored at the specified attribute name

widgetSchemaArray

An optional property that can be added to each setting to control whether it should be displayed to the user while editing in Page Builder. This does not clear the value in the setting, just controls the display of the setting.

The ID of the `settings` object the conditional attribute is related to. You must define the key within the same settings array as the conditional property to scope the conditional logic to the relevant settings group.

Specifies the operation used to determine whether to display the setting. The `IN` operator is currently the only supported operator. The setting will be displayed if the conditional’s `value` property is equal to the selected value of the `selectOptions`. 

A single-object array containing a value from the `typeMeta`'s `selectOptions`.

widgetSchemaConditional

**Hidden.** Use the **hidden** settings type to create controls that have no user interface drawn in Page Builder. Hidden settings are not grouped into any other tabs or arrays.

widgetSchemaHidden

For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.

The default value to use when rendering the widget for the first time. Make sure to set sensible defaults to make your widget easier to use.

The variable name where the setting value will be available in the widget template.

The user friendly message to inform the user how this setting will be used.

The type of setting component to display. You can view the list of elements below to discover which are available to use.

For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.

Additional information needed based on the selected setting type.

widgetSchemaSetting_Base

**Tab.** Use the **tab** settings type to create settings visible in Page Builder.

The user-friendly message to inform the user how this setting will be used.

widgetSchemaTabSections

The type of setting component to display.

widgetSchemaTab

widgetSchemaTabSectionsSettings

The GraphQL Storefront API query that provides widget data.

The widget template HTML. Supports Handlebars and Paper helpers.

widgetTemplate_Base

The identifier to the current version of this widget template.

A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.

widgetTemplate_Full

The id of the channel on which to create this template. Defaults to the first channel created on the store.

Handlebars HTML content. Also has access to Stencil Paper helpers.

widgetTemplate_Post

string

The id of the channel on which to place this template.

Can be added to create a new widget template version instead of updating the current one.

widgetTemplate_Put

widget_Base

The ID of the channel on which this widget exists.

The identifier of the widget template version associated with this widget.

widget_Full

The ID of the channel on which to create this widget. Defaults to the first channel created on the store.

widget_Post

Upgrade the Widget to latest version of the WidgetTemplate.

widget_Put

### OAuth scopes

| UI Name | Permission | Parameter |
|:--------|:-----------|:----------|
|  Content | modify | `store_v2_content` |
|  Content | read-only | `store_v2_content_read_only` |

### Authentication header

| Header | Argument | Description |
|:-------|:---------|:------------|
| `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |

### Further reading

For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).

For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).

For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).

X-Auth-Token

BigCommerce

Create and manage widget templates, widgets, regions, and placements.

## Subresources

### Widget templates
[Widget templates](/docs/rest-content/widgets/widget-template) are reusable Handlebars-enabled HTML templates that define the structure of the widget on a page.

### Widgets
[Widgets](/docs/rest-content/widgets/widget) are units of content placed on specific pages in a Stencil theme. Widgets consist of a widget configuration and a widget template UUID and render as part of the storefront’s HTML.

### Regions
[Regions](/docs/rest-content/widgets/regions) are specific locations in the Stencil theme template files where you can place a widget.

### Placements
[Placements](/docs/rest-content/widgets/placement) determine the region where you place widgets and in what order.

## Additional Information

* [Widgets API Overview](/docs/storefront/widgets)
* [Widget UI Schema](/docs/storefront/widgets/input-reference/schema)
* [Widget UI Input Types](/docs/storefront/widgets/input-reference/settings)

Widgets

Creates a **Placement**.

**Template Files**

To view the list of values accepted by the `template_file` property, including **custom** templates, see [Placements](/docs/storefront/widgets#placements).

Returns a list of unique **Theme Regions** in a file.

Creates a **Widget Template**.

***Note:*** *There is a limit of 1000 custom widget templates per store.*

**Required Fields**
* name
* template

Header Images

Render a widget template and return the widget html.

Returns a list of **Widgets**. Optional parameters can be passed in.

Creates a **Widget**.

**Note:** There is a limit of 100,000 widgets per store and 150 widgets per page. For more information, see [Store Limits](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits).

Widget

Create a Widget

Get All Widgets

Get a Widget

Update a Widget

Delete a Widget