BigCommerce Widgets is a software platform that provides e-commerce businesses with the tools to create and customize widgets for their online stores. These widgets can range from product sliders and image galleries to social media feeds and custom contact forms. By using BigCommerce Widgets, businesses can enhance the functionality and aesthetics of their websites, ultimately improving the user experience and driving more conversions.
openapi: 3.0.1
info:
title: BigCommerce Widgets
version: ''
description: >-
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)
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
tags:
- name: Placement
description: BigCommerce Placements API Definition.
- name: Regions
- name: Widget
- name: Widget Template
description: BigCommerce Widget Templates API Definition.
security:
- X-Auth-Token: []
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
paths:
/content/widget-templates:
post:
tags:
- Widget Template
summary: BigCommerce Create a Widget Template
operationId: createWidgetTemplate
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/widgetTemplate_Post'
required: true
x-examples:
application/json: |-
{
"name": "Header Images",
"template": "{{#each images}}{{/each}}"
}
Custom Configuration Widget: |-
{
"name":"Header Images",
"template":"{{#each images}}{{/each}}",
"schema":[
{
"type":"array",
"label":"Images",
"id":"images",
"defaultCount":3,
"entryLabel":"Image",
"thumbnail":"imageUrl.src",
"schema":[
{
"type":"tab",
"label":"Content",
"sections":[
{
"settings":[
{
"type":"imageManager",
"id":"imageUrl",
"default":{
"src":"https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on",
"type":"IMAGE_MANAGER"
}
},
{
"label":"Link",
"type":"input",
"id":"link",
"default":"#"
}
]
}
]
}
]
}
]
}
responses:
'200':
$ref: '#/components/responses/WidgetTemplate_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: >-
Creates a **Widget Template**.
***Note:*** *There is a limit of 1000 custom widget templates per
store.*
**Required Fields**
* name
* template
get:
tags:
- Widget Template
operationId: getWidgetTemplates
parameters:
- name: page
description: |
Specifies the page number in a limited (paginated) list of products.
required: false
in: query
schema:
type: integer
- name: limit
description: >
Controls the number of items per page in a limited (paginated) list
of products.
required: false
in: query
schema:
type: integer
- in: query
name: widget_template_kind
description: The kind of widget template.
required: false
schema:
type: string
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/ContentType'
- in: query
name: channel_id:in
description: Filter items by channel_id.
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/WidgetTemplateCollection_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Returns a list of **Widget Templates**.
summary: BigCommerce Get All Widget Templates
/content/widget-templates/{uuid}/preview:
post:
tags:
- Widget Template
summary: BigCommerce Render a Widget Template
description: Render a widget template and return the widget html.
operationId: previewWidget
parameters:
- $ref: '#/components/parameters/TemplateUUID'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetTemplatePreview'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WidgetTemplatePreviewResponse'
'404':
description: Not Found
'422':
description: Unprocessable Entity
parameters:
- schema:
type: string
name: uuid
in: path
required: true
description: The identifier for a specific widget.
/content/widget-templates/{uuid}:
get:
tags:
- Widget Template
summary: BigCommerce Get a Widget Template
operationId: getWidgetTemplate
parameters:
- schema:
type: string
in: query
name: version_uuid
description: >-
This is an optional query parameter used to attempt to fetch a
specific Widget Template version.
responses:
'200':
$ref: '#/components/responses/WidgetTemplate_Resp'
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Returns a single **Widget Template**.
put:
tags:
- Widget Template
summary: BigCommerce Update a Widget Template
operationId: updateWidgetTemplate
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/widgetTemplate_Put'
required: true
x-examples:
application/json:
name: Header Images
template: '{{#each images}}{{/each}}'
create_new_version: true
responses:
'200':
$ref: '#/components/responses/WidgetTemplate_Resp'
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Updates a **Widget Template**.
delete:
tags:
- Widget Template
summary: BigCommerce Delete A Widget Template
operationId: deleteWidgetTemplate
responses:
'204':
description: An empty response.
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Deletes a **Widget Template**.
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/TemplateUUID'
/content/widgets:
post:
tags:
- Widget
summary: BigCommerce Create a Widget
operationId: createWidget
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/widget_Post'
required: true
x-examples:
application/json:
name: Header Images
template: '{{#each images}}{{/each}}'
widget_configuration:
images:
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/500x659/products/85/282/livingwithplants_grande__26452.1456436666.jpg?c=2&imbypass=on
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on
widget_template_uuid: f8459145-da8f-4d98-93e4-83aa47da61c6
responses:
'200':
$ref: '#/components/responses/Widget_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: >-
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).
get:
tags:
- Widget
summary: BigCommerce Get All Widgets
operationId: getWidgets
parameters:
- name: page
description: |
Specifies the page number in a limited (paginated) list of products.
required: false
in: query
schema:
type: integer
- name: limit
description: >
Controls the number of items per page in a limited (paginated) list
of products.
required: false
in: query
schema:
type: integer
- in: query
name: widget_template_kind
description: The kind of widget template.
required: false
schema:
type: string
- in: query
name: widget_template_uuid
description: The identifier for a specific widget template.
required: false
schema:
type: string
format: uuid
- in: query
name: name
description: The URL encoded name of the widget.
schema:
type: string
- in: query
name: name:in
description: >-
Use to pass in comma-separated list of widget names. Example:
`/widgets?name:in=test-widget-name,header%20images`
schema:
type: array
items: {}
- in: query
name: channel_id:in
description: Filter items by channel_id.
schema:
type: integer
- schema:
type: string
in: query
name: site_id:in
description: A comma-separated list of site ids to filter the results by.
responses:
'200':
$ref: '#/components/responses/WidgetCollection_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Returns a list of **Widgets**. Optional parameters can be passed in.
parameters:
- $ref: '#/components/parameters/Accept'
/content/widgets/{uuid}:
get:
tags:
- Widget
summary: BigCommerce Get a Widget
operationId: getWidget
responses:
'200':
$ref: '#/components/responses/Widget_Resp'
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Returns a single **Widget**.
put:
tags:
- Widget
summary: BigCommerce Update a Widget
operationId: updateWidget
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/widget_Put'
required: true
x-examples:
application/json:
name: Header Images
widget_configuration:
images:
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/500x659/products/85/282/livingwithplants_grande__26452.1456436666.jpg?c=2&imbypass=on
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on
widget_template_uuid: f8459145-da8f-4d98-93e4-83aa47da61c6
responses:
'200':
$ref: '#/components/responses/Widget_Resp'
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Updates a **Widget**.
delete:
tags:
- Widget
summary: BigCommerce Delete a Widget
operationId: deleteWidget
responses:
'204':
description: An empty response.
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Deletes a **Widget**.
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/WidgetUUID'
/content/placements:
post:
tags:
- Placement
summary: BigCommerce Create a Placement
operationId: createPlacement
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/placement_Post'
required: true
x-examples:
application/json:
widget_uuid: a8940709-5655-4401-a341-62c44e3180b2
entity_id: '21'
template_file: pages/category
status: active
sort_order: 1
region: category_header_banner
responses:
'200':
$ref: '#/components/responses/Placement_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: >-
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).
get:
tags:
- Placement
summary: BigCommerce Get All Placements
operationId: getPlacements
parameters:
- name: page
description: |
Specifies the page number in a limited (paginated) list of products.
required: false
in: query
schema:
type: integer
- name: limit
description: >
Controls the number of items per page in a limited (paginated) list
of products.
required: false
in: query
schema:
type: integer
- in: query
name: widget_template_kind
description: The kind of widget template.
required: false
schema:
type: string
- in: query
name: template_file
description: 'The template file, for example: `pages/home`.'
required: false
schema:
type: string
- name: widget_uuid
description: The identifier for a specific widget.
in: query
required: false
schema:
type: string
format: uuid
- in: query
name: widget_template_uuid
description: The identifier for a specific widget template.
required: false
schema:
type: string
format: uuid
- $ref: '#/components/parameters/ChannelIDInParam'
- $ref: '#/components/parameters/SiteIDInParam'
responses:
'200':
$ref: '#/components/responses/PlacementsCollection_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Returns a list of **Placements**.
parameters:
- $ref: '#/components/parameters/Accept'
/content/placements/{uuid}:
get:
tags:
- Placement
summary: BigCommerce Get a Placement
operationId: getPlacement
responses:
'200':
$ref: '#/components/responses/Placement_Resp'
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Returns a single **Placement**.
put:
tags:
- Placement
summary: BigCommerce Update a Placement
operationId: updatePlacement
parameters:
- $ref: '#/components/parameters/ContentType'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/placement_Put'
required: true
x-examples:
application/json:
sort_order: 1
region: home_header_image
template_file: pages/home
status: active
responses:
'200':
$ref: '#/components/responses/Placement_Resp'
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Updates a **Placement**.
delete:
tags:
- Placement
summary: BigCommerce Delete a Placement
operationId: deletePlacement
responses:
'204':
description: An empty response.
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
description: Deletes a **Placement**.
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/PlacementUUID'
/content/regions:
get:
responses:
'200':
$ref: '#/components/responses/ThemeRegions_Resp'
'404':
$ref: '#/components/responses/Error404_Resp'
'422':
$ref: '#/components/responses/Error422_Resp'
summary: BigCommerce Get Theme Regions
description: Returns a list of unique **Theme Regions** in a file.
operationId: getContentRegions
tags:
- Regions
parameters:
- $ref: '#/components/parameters/Accept'
- in: query
name: template_file
description: 'The template file, for example: `templateFile=pages/home`.'
required: true
schema:
type: string
components:
parameters:
TemplateUUID:
name: uuid
description: The identifier for a specific template.
required: true
in: path
schema:
type: string
format: uuid
FilterWidgetTemplateUUIDParam:
in: query
name: widget_template_uuid
description: The identifier for a specific widget template.
required: false
schema:
type: string
format: uuid
FilterWidgetTemplateKindParam:
in: query
name: widget_template_kind
description: The kind of widget template.
required: false
schema:
type: string
FilterTemplateFileParam:
in: query
name: template_file
description: 'The template file, for example: `pages/home`.'
required: false
schema:
type: string
RequiredTemplateFile:
in: query
name: templateFile
description: 'The template file, for example: `templateFile=pages/home`.'
required: true
schema:
type: string
LayoutUUID:
name: uuid
description: The identifier for a specific layout.
required: true
in: path
schema:
type: string
format: uuid
PlacementUUID:
name: uuid
description: The identifier for a specific placement.
required: true
in: path
schema:
type: string
format: uuid
WidgetUUID:
name: uuid
description: The identifier for a specific widget.
required: true
in: path
schema:
type: string
format: uuid
FilterWidgetUUIDParam:
name: widget_uuid
description: The identifier for a specific widget.
in: query
required: false
schema:
type: string
format: uuid
PageParam:
name: page
description: |
Specifies the page number in a limited (paginated) list of products.
required: false
in: query
schema:
type: integer
LimitParam:
name: limit
description: >
Controls the number of items per page in a limited (paginated) list of
products.
required: false
in: query
schema:
type: integer
QueryWidgetsParam:
name: query
in: query
description: |
The query string associated with a widget's name and description.
schema:
type: string
Accept:
name: Accept
in: header
required: true
description: >-
The [MIME
type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
of the response body.
schema:
type: string
default: application/json
ContentType:
name: Content-Type
in: header
required: true
description: >-
The [MIME
type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types)
of the request body.
schema:
type: string
default: application/json
ChannelIDInParam:
name: channel_id:in
in: query
required: false
schema:
type: string
description: A comma-separated list of channel ids to filter the results by.
SiteIDInParam:
name: site_id:in
in: query
required: false
schema:
type: string
description: A comma-separated list of site IDs to filter the results by.
responses:
ThemeRegions_Resp:
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/themeRegion'
meta:
$ref: '#/components/schemas/Meta'
examples:
response:
value:
data:
- name: header_bottom
- name: category_header_banner
meta: {}
LayoutCollectionResponse:
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
properties:
uuid:
type: string
format: uuid
description: The primary identifier.
entity_id:
type: string
description: The specific instance of a page
template_file:
type: string
description: The page template name.
region:
type: string
description: >-
The name of the region defined in the Stencil theme
file.
markup:
type: string
description: >-
The HTML layout which defines complex positioning for
placements.
date_created:
type: string
format: date-time
description: The date on which this object was initially created.
date_modified:
type: string
format: date-time
description: The date on which this object was last updated.
title: Layout
meta:
type: object
description: >-
Data about the response, including pagination and collection
totals.
properties:
pagination:
type: object
description: >
Data about the response, including pagination and
collection totals.
properties:
total:
type: integer
description: |
Total number of items in the result set.
count:
type: integer
description: |
Total number of items in the collection response.
per_page:
type: integer
description: >
The amount of items returned in the collection per
page, controlled by the limit parameter.
current_page:
type: integer
description: |
The page you are currently on within the collection.
total_pages:
type: integer
description: |
The total number of pages in the collection.
links:
type: object
description: >
Pagination links for the previous and next parts of
the whole collection.
properties:
previous:
type: string
description: >
Link to the previous page returned in the
response.
current:
type: string
description: |
Link to the current page returned in the response.
next:
type: string
description: |
Link to the next page returned in the response.
title: Collection Meta
examples:
response:
value:
data:
- uuid: cacdadcf-07ec-43f3-aec4-f8e3382d7618
template_file: pages/category
entity_id: '21'
region: category_header_banner
markup: ' '
date_created: '2019-02-25T18:38:08.455Z'
date_modified: '2019-02-25T18:38:08.455Z'
meta:
pagination:
total: 1
count: 1
per_page: 50
current_page: 1
total_pages: 1
LayoutResponse:
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
properties:
uuid:
type: string
format: uuid
description: The primary identifier.
entity_id:
type: string
description: The specific instance of a page
template_file:
type: string
description: The page template name.
region:
type: string
description: >-
The name of the region defined in the Stencil theme
file.
markup:
type: string
description: >-
The HTML layout which defines complex positioning for
placements.
date_created:
type: string
format: date-time
description: The date on which this object was initially created.
date_modified:
type: string
format: date-time
description: The date on which this object was last updated.
title: Layout
PlacementsCollection_Resp:
description: ''
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/placement_Full'
meta:
$ref: '#/components/schemas/metaCollection'
examples:
response:
value:
data:
- channel_id: 1
date_created: '2020-12-21T20:43:16.796Z'
date_modified: '2020-12-21T20:43:16.796Z'
entity_id: '21'
region: category_header_banner
sort_order: 1
status: active
template_file: pages/category
uuid: 89eac5b3-91d7-48e5-92e7-ff53ecf07f8c
widget:
channel_id: 1
date_created: '2020-12-21T19:54:16.406Z'
date_modified: '2020-12-21T20:40:45.173Z'
description: ''
name: Header Images
storefront_api_query_params: {}
uuid: 1f05183e-dfa4-4583-af28-250b47e177b2
version_uuid: c863f77b-e5b4-4462-a9ed-2aff9005140e
widget_configuration:
_:
id: 1f05183e-dfa4-4583-af28-250b47e177b2
images:
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/500x659/products/85/282/livingwithplants_grande__26452.1456436666.jpg?c=2&imbypass=on
- image_source: >-
https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on
widget_template:
channel_id: 1
client_rerender: false
current_version_uuid: c863f77b-e5b4-4462-a9ed-2aff9005140e
date_created: '2020-12-21T19:49:29.110Z'
date_modified: '2020-12-21T19:49:29.110Z'
icon_name: default
kind: custom
# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/widgets-openapi-original.yml