Widget Template | BigCommerce Dev Center

Create a Widget Template

POST https://api.bigcommerce.com/stores/{store_hash}/v3/content/widget-templates

Request

Creates a Widget Template.

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

Required Fields

name
template

Authentication

X-Auth-Token in header - required

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

namestring
required
User-friendly name.
schemaarray[]
The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see Widget UI Schema.
templatestring
required
Handlebars HTML content. Also has access to Stencil Paper helpers.
storefront_api_querystring
The GraphQL Storefront API query that provides widget data.
channel_idinteger
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",
                "value": [
                  null
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "template": "string",
  "storefront_api_query": "string",
  "channel_id": 0
}

Response

Body

application/json

data

metaobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/content/widget-templates

Request

Returns a list of Widget Templates.

Authentication

X-Auth-Token in header - required

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 - integer
Filter items by channel_id.

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: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

dataarray[object]
metaobject
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",
      "icon_name": "default",
      "kind": "custom",
      "name": "Simple List",
      "schema": [],
      "storefront_api_query": "",
      "template": "<ul>{{#each list_items}}<li style='color:{{color}};'>{{text}}</li>{{/each}}</ul>",
      "template_engine": "handlebars_v3",
      "uuid": "42b42cbb-e2d8-4f2a-97ea-06755032115a"
    },
    {
      "channel_id": 1,
      "client_rerender": false,
      "current_version_uuid": "bc820372-368e-4a96-a6d6-f313edba5617",
      "date_created": "2020-12-21T19:38:08.036Z",
      "date_modified": "2020-12-21T19:38:08.036Z",
      "icon_name": "default",
      "kind": "custom",
      "name": "Simple Text with Styling",
      "schema": [],
      "storefront_api_query": "",
      "template": "{{text}}\n",
      "template_engine": "handlebars_v3",
      "uuid": "17dcc919-982a-4cc0-8ede-a5b49f9ab6dc"
    },
    {
      "channel_id": 1,
      "client_rerender": false,
      "current_version_uuid": "873b0a03-b219-46ec-8f06-c3c4522ef25d",
      "date_created": "2020-12-21T19:38:30.223Z",
      "date_modified": "2020-12-21T19:38:30.223Z",
      "icon_name": "default",
      "kind": "custom",
      "name": "YouTube Embed",
      "schema": [],
      "storefront_api_query": "",
      "template": "",
      "template_engine": "handlebars_v3",
      "uuid": "d9e7fd0e-d5c2-45c9-8919-ce68a5590c12"
    },
    {
      "channel_id": 1,
      "client_rerender": false,
      "current_version_uuid": "8fa7ff13-fcfb-4106-9c32-5a084224a444",
      "date_created": "2020-12-21T19:38:46.557Z",
      "date_modified": "2020-12-21T19:38:46.557Z",
      "icon_name": "default",
      "kind": "custom",
      "name": "Slider Template",
      "schema": [],
      "storefront_api_query": "",
      "template": "{{#each slides}}\n{{/each}}",
      "template_engine": "handlebars_v3",
      "uuid": "30714957-0e01-4c4e-8551-25591261d0d0"
    },
    {
      "channel_id": 0,
      "client_rerender": false,
      "current_version_uuid": "7494d009-c695-43ce-a1eb-ba75ef663ba2",
      "date_created": "2020-06-23T18:07:12.110Z",
      "date_modified": "2020-06-23T18:07:12.110Z",
      "icon_name": "default",
      "kind": "pp-cartpage-fullbanner",
      "name": "PayPal Credit Banner - Cart Page (728x90)",
      "schema": [],
      "storefront_api_query": "",
      "template": "",
      "template_engine": "handlebars_v3",
      "uuid": "2ff24732-6848-47ba-9a7f-c8b1d444f270"
    },
    {
      "channel_id": 0,
      "client_rerender": false,
      "current_version_uuid": "ee4978a6-31f9-47e2-ab38-810dd1c78e34",
      "date_created": "2020-06-23T18:07:12.136Z",
      "date_modified": "2020-06-23T18:07:12.136Z",
      "icon_name": "default",
      "kind": "pp-homepage-fullbanner",
      "name": "PayPal Credit Banner - Home Page (728x90)",
      "schema": [],
      "storefront_api_query": "",
      "template": "",
      "template_engine": "handlebars_v3",
      "uuid": "3002bf5b-5eca-4ac2-8f1f-5240c2b74712"
    }
  ],
  "meta": {
    "pagination": {
      "total": 7,
      "count": 7,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Render a Widget Template

POST https://api.bigcommerce.com/stores/{store_hash}/v3/content/widget-templates/{uuid}/preview

Request

Render a widget template and return the widget html.

Authentication

X-Auth-Token in header - required

Parameters

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

Body

application/json

widget_configurationobject
The JSON data that populates the template.

example

{
  "widget_configuration": {}
}

Response

Success

Body

object | application/json

data

example

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

Get a Widget Template

GET https://api.bigcommerce.com/stores/{store_hash}/v3/content/widget-templates/{uuid}

Request

Returns a single Widget Template.

Authentication

X-Auth-Token in header - required

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 attempt 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: xxxxxxxxxxxxxxxxx'

Response

Body

application/json

data

metaobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/content/widget-templates/{uuid}

Request

Updates a Widget Template.

Authentication

X-Auth-Token in header - required

Parameters

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

Body

application/json

namestring
The user-friendly name.
schemaarray[]
The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see Widget UI Schema.
templatestring
The widget template HTML. Supports Handlebars and Paper helpers.
storefront_api_querystring
The GraphQL Storefront API query that provides widget data.

create_new_versionboolean
Can be added to create a new widget template version instead of updating the current one.
channel_idinteger
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",
                "value": [
                  null
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "template": "string",
  "storefront_api_query": "string",
  "create_new_version": true,
  "channel_id": 0
}

Response

Body

application/json

data

metaobject
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 https://api.bigcommerce.com/stores/{store_hash}/v3/content/widget-templates/{uuid}

Request

Deletes a Widget Template.

Authentication

X-Auth-Token in header - required

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: xxxxxxxxxxxxxxxxx'

Response

An empty response.

Create a Widget Template

Request

Authentication

Parameters

Body

namestringrequired

schemaarray[]

templatestringrequired

storefront_api_querystring

channel_idinteger

example

Response

Body

data

metaobject

response

Get All Widget Templates

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

response

Render a Widget Template

Request

Authentication

Parameters

Body

widget_configurationobject

example

Response

Body

data

example

Get a Widget Template

Request

Authentication

Parameters

example

Response

Body

data

metaobject

response

Update a Widget Template

Request

Authentication

Parameters

Body

namestring

schemaarray[]

templatestring

storefront_api_querystring

create_new_versionboolean

channel_idinteger

example

Response

Body

data

metaobject

response

Delete A Widget Template

Request

Authentication

Parameters

example

Response

namestring
required

templatestring
required