Docs
Content API
Widgets
Widget Template

Widget Template

Create a Widget Template

POST /content/widget-templates

Request

Creates a Widget Template.

Note: There is a limit of 1000 custom widget templates per channel, and a limit of 5000 across all channels.

Required Fields

  • name
  • template

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json

  • name    string
    required

    User-friendly name.

  • schema    array[]

    The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see Widget UI Schema.

  • template    string
    required

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

  • storefront_api_query    string

    The GraphQL Storefront API query that provides widget data.

  • channel_id    integer

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

example

{
"name": "string",
"schema": [
{
"type": "tab",
"label": "Content",
"sections": [
{
"label": "Product",
"settings": [
{
"type": "alignment",
"label": "string",
"id": "string",
"default": "string",
"typeMeta": {
"selectOptions": [
{
"label": "Image",
"value": "image"
}
]
},
"conditional": {
"key": "backgroundType",
"operator": "IN",

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

response

{
"data": {
"channel_id": 1,
"client_rerender": false,
"current_version_uuid": "4bd7619e-7992-4454-8610-84fb16449761",
"date_created": "2020-12-21T19:36:16.896Z",
"date_modified": "2020-12-21T19:36:16.896Z",
"icon_name": "default",
"kind": "custom",
"name": "Header Images",
"schema": [],
"storefront_api_query": "",
"template": "{{#each images}}{{/each}}",
"template_engine": "handlebars_v3",
"uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
},
"meta": {}
}

Get All Widget Templates

GET /content/widget-templates

Request

Returns a list of Widget Templates.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • page in query - integer

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

  • limit in query - integer

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

  • widget_template_kind in query - string
    The kind of widget template.
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.
  • channel_id:in in query - array
    A comma-separated list of channel ids to filter the results by.
    Type: array[integer]

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/widget-templates' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

response

{
"data": [
{
"channel_id": 1,
"client_rerender": false,
"current_version_uuid": "4bd7619e-7992-4454-8610-84fb16449761",
"date_created": "2020-12-21T19:36:16.896Z",
"date_modified": "2020-12-21T19:36:16.896Z",
"icon_name": "default",
"kind": "custom",
"name": "Header Images",
"schema": [],
"storefront_api_query": "",
"template": "{{#each images}}{{/each}}",
"template_engine": "handlebars_v3",
"uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
},
{
"channel_id": 1,
"client_rerender": false,
"current_version_uuid": "c23dd66b-fa3f-451d-88ef-9f4082c6051e",
"date_created": "2020-12-21T19:36:59.384Z",
"date_modified": "2020-12-21T19:36:59.384Z",

Render a Widget Template

POST /content/widget-templates/{uuid}/preview

Request

Render a widget template and return the widget html.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • uuid in path - string
    required
    The identifier for a specific template.

Body

object | application/json

  • widget_configuration    object

    The JSON data that populates the template.

example

{
"widget_configuration": {}
}

Response

Success

Body

object | application/json

  • data    object

example

{
"data": {
"html": "string"
}
}

Get a Widget Template

GET /content/widget-templates/{uuid}

Request

Returns a single Widget Template.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • uuid in path - string
    required
    The identifier for a specific template.
  • version_uuid in query - string
    This is an optional query parameter used to fetch a specific widget template version.

example

curl --request GET \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/widget-templates/[uuid]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

response

{
"data": {
"channel_id": 1,
"client_rerender": false,
"current_version_uuid": "4bd7619e-7992-4454-8610-84fb16449761",
"date_created": "2020-12-21T19:36:16.896Z",
"date_modified": "2020-12-21T19:36:16.896Z",
"icon_name": "default",
"kind": "custom",
"name": "Header Images",
"schema": [],
"storefront_api_query": "",
"template": "{{#each images}}{{/each}}",
"template_engine": "handlebars_v3",
"uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
},
"meta": {}
}

Update a Widget Template

PUT /content/widget-templates/{uuid}

Request

Updates a Widget Template.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • uuid in path - string
    required
    The identifier for a specific template.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json

  • name    string

    The user-friendly name.

  • schema    array[]

    The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see Widget UI Schema.

  • template    string

    The widget template HTML. Supports Handlebars and Paper helpers.

  • storefront_api_query    string

    The GraphQL Storefront API query that provides widget data.

  • create_new_version    boolean

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

  • channel_id    integer

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

example

{
"name": "string",
"schema": [
{
"type": "tab",
"label": "Content",
"sections": [
{
"label": "Product",
"settings": [
{
"type": "alignment",
"label": "string",
"id": "string",
"default": "string",
"typeMeta": {
"selectOptions": [
{
"label": "Image",
"value": "image"
}
]
},
"conditional": {
"key": "backgroundType",
"operator": "IN",

Response

Body

object | application/json

  • data    object

  • meta    object

    Response metadata.

response

{
"data": {
"channel_id": 1,
"client_rerender": false,
"current_version_uuid": "4bd7619e-7992-4454-8610-84fb16449761",
"date_created": "2020-12-21T19:36:16.896Z",
"date_modified": "2020-12-21T19:36:16.896Z",
"icon_name": "default",
"kind": "custom",
"name": "Header Images",
"schema": [],
"storefront_api_query": "",
"template": "{{#each images}}{{/each}}",
"template_engine": "handlebars_v3",
"uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6"
},
"meta": {}
}

Delete A Widget Template

DELETE /content/widget-templates/{uuid}

Request

Deletes a Widget Template.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • uuid in path - string
    required
    The identifier for a specific template.

example

curl --request DELETE \
--url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/widget-templates/[uuid]' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: {{token}}'

Response

An empty response.
Did you find what you were looking for?
Delete a WidgetCreate a Widget Template