BigCommerce
BigCommerce Widget API

The Widget API from BigCommerce — 2 operation(s) for widget.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Widget API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
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
security:
- X-Auth-Token: []
tags:
- name: Widget
paths:
  /content/widgets:
    parameters:
    - $ref: '#/components/parameters/Accept'
    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.
  /content/widgets/{uuid}:
    parameters:
    - $ref: '#/components/parameters/Accept'
    - $ref: '#/components/parameters/WidgetUUID'
    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**.
components:
  schemas:
    metaCollection:
      type: object
      description: Data about the response, including pagination and collection totals.
      title: metaCollection
      properties:
        pagination:
          $ref: '#/components/schemas/pagination'
      x-internal: false
    widget_Post:
      title: widget_Post
      x-internal: false
      type: object
      properties:
        name:
          type: string
          description: User friendly name.
        description:
          type: string
          description: The user-friendly description.
        widget_configuration:
          type: object
          description: The JSON data that populates the template.
          format: json
        widget_template_uuid:
          type: string
          description: The widget template UUID.
        channel_id:
          type: integer
          description: The ID of the channel on which to create this widget. Defaults to the first channel created on the store.
      required:
      - name
      - widget_template_uuid
    widgetSchema:
      type: array
      description: '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). '
      title: ''
      items:
        anyOf:
        - $ref: '#/components/schemas/widgetSchemaTab'
        - $ref: '#/components/schemas/widgetSchemaArray'
        - $ref: '#/components/schemas/widgetSchemaHidden'
      x-internal: false
    Meta:
      title: Response meta
      type: object
      properties: {}
      additionalProperties: true
      description: Response metadata.
    widget_Full:
      title: widget_Full
      allOf:
      - $ref: '#/components/schemas/widget_Base'
      - type: object
        properties:
          uuid:
            type: string
            format: uuid
            description: The primary identifier.
          widget_template:
            $ref: '#/components/schemas/widgetTemplate_Full'
          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.
          version_uuid:
            type: string
            description: The identifier of the widget template version associated with this widget.
          channel_id:
            type: integer
            description: The ID of the channel on which this widget exists.
      x-internal: false
    widgetSchemaHidden:
      type: object
      title: widgetSchemaHidden
      description: '**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.'
      x-internal: false
      properties:
        type:
          type: string
          enum:
          - hidden
          example: hidden
        settings:
          type: array
          items:
            type: object
            title: widgetSchemaSetting_Base
            description: For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.
            properties:
              type:
                type: string
                description: '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.'
                enum:
                - alignment
                - boolean
                - boxModel
                - code
                - color
                - imageManager
                - input
                - number
                - productId
                - productImage
                - range
                - regexInput
                - select
                - text
                - toggle
              label:
                type: string
                description: The user friendly message to inform the user how this setting will be used.
              id:
                type: string
                description: The variable name where the setting value will be available in the widget template.
              default:
                type: string
                description: 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.
              typeMeta:
                type: object
                description: Additional information needed based on the selected setting type.
                properties:
                  selectOptions:
                    type: array
                    items:
                      type: object
                      properties:
                        label:
                          type: string
                          example: Image
                        value:
                          type: string
                          example: image
              conditional:
                type: object
                title: widgetSchemaConditional
                description: 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.
                x-examples:
                  Conditional attribute:
                    key: backgroundType
                    operator: IN
                    value:
                    - color
                properties:
                  key:
                    type: string
                    description: The ID of the `setting` object the conditional attribute is related to.
                    example: backgroundType
                  operator:
                    type: string
                    description: '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`. '
                    example: IN
                  value:
                    type: array
                    description: A single-object array containing a value from the `typeMeta`'s `selectOptions`.
                    items: {}
    widget_Base:
      type: object
      title: widget_Base
      properties:
        name:
          type: string
          description: The user-friendly name.
        description:
          type: string
          description: The user-friendly description.
        widget_configuration:
          type: object
          format: json
          description: The JSON data that populates the template.
      x-internal: false
      x-examples: {}
    widgetSchemaArray:
      type: object
      title: widgetSchemaArray
      description: '**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.'
      properties:
        type:
          type: string
          enum:
          - array
        label:
          type: string
        id:
          type: string
        defaultCount:
          type: integer
          description: number of elements in the list to display by default.
        entryLabel:
          type: string
          description: name for each element in the list
        thumbnail:
          type: object
          description: used to display an image stored at the specified attribute name
          properties:
            type:
              type: string
              example: image
            valueKey:
              type: string
              example: imageUrl.src
        schema:
          description: The schema used for each element in the array.
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/widgetSchemaHidden'
            - $ref: '#/components/schemas/widgetSchemaTab'
      x-internal: false
    widgetTemplate_Base:
      type: object
      title: widgetTemplate_Base
      properties:
        name:
          type: string
          description: The user-friendly name.
        schema:
          $ref: '#/components/schemas/widgetSchema'
        template:
          type: string
          format: html
          description: The widget template HTML. Supports Handlebars and Paper helpers.
        storefront_api_query:
          type: string
          description: The GraphQL Storefront API query that provides widget data.
      description: ''
      x-internal: false
    widgetTemplate_Full:
      allOf:
      - $ref: '#/components/schemas/widgetTemplate_Base'
      - type: object
        properties:
          uuid:
            type: string
            format: uuid
            description: The primary identifier.
          kind:
            type: string
            description: The kind of widget template.
          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.
          current_version_uuid:
            type: string
            description: The identifier to the current version of this widget template.
          icon_name:
            type: string
            default: default
            description: A read-only value. Do not attempt to set or modify this value in a POST or PUT operation.
      title: widgetTemplate_Full
      description: ''
      x-internal: false
    widgetSchemaTab:
      type: object
      title: widgetSchemaTab
      description: '**Tab.** Use the **tab** settings type to create settings visible in Page Builder.'
      properties:
        type:
          type: string
          description: The type of setting component to display.
          enum:
          - tab
        label:
          type: string
          example: Content
          description: The user-friendly message to inform the user how this setting will be used.
        sections:
          type: array
          description: Groups of related settings.
          items:
            type: object
            title: widgetSchemaTabSections
            properties:
              label:
                type: string
                description: The user-friendly message to inform the user how this setting will be used.
                example: Product
              settings:
                type: array
                description: For examples of schema settings, see [Widget UI Input Types](/docs/storefront/widgets/input-reference/settings).
                items:
                  type: object
                  title: widgetSchemaSetting_Base
                  description: For examples of each type of setting, see [Page Builder > Schema Settings](/docs/storefront/widgets/input-reference/settings#alignment) in Theme Docs.
                  properties:
                    type:
                      type: string
                      description: '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.'
                      enum:
                      - alignment
                      - boolean
                      - boxModel
                      - code
                      - color
                      - imageManager
                      - input
                      - number
                      - productId
                      - productImage
                      - range
                      - regexInput
                      - select
                      - text
                      - toggle
                    label:
                      type: string
                      description: The user friendly message to inform the user how this setting will be used.
                    id:
                      type: string
                      description: The variable name where the setting value will be available in the widget template.
                    default:
                      type: string
                      description: 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.
                    typeMeta:
                      type: object
                      description: Additional information needed based on the selected setting type.
                      properties:
                        selectOptions:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                                example: Image
                              value:
                                type: string
                                example: image
                    conditional:
                      type: object
                      title: widgetSchemaConditional
                      description: 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.
                      x-examples:
                        Conditional attribute:
                          key: backgroundType
                          operator: IN
                          value:
                          - color
                      properties:
                        key:
                          type: string
                          description: The ID of the `setting` object the conditional attribute is related to.
                          example: backgroundType
                        operator:
                          type: string
                          description: '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`. '
                          example: IN
                        value:
                          type: array
                          description: A single-object array containing a value from the `typeMeta`'s `selectOptions`.
                          items: {}
      x-internal: false
      x-examples: {}
    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: pagination
      x-internal: false
    error_Base:
      type: object
      description: Error payload for the BigCommerce API.
      properties:
        status:
          description: The HTTP status code.
          type: integer
        title:
          description: The error title describing the particular error.
          type: string
        type:
          type: string
        instance:
          type: string
        errors:
          type: object
      x-internal: false
      title: error_Base
    widget_Put:
      title: widget_Put
      allOf:
      - $ref: '#/components/schemas/widget_Base'
      - type: object
        properties:
          widget_template_uuid:
            type: string
            description: The widget template UUID.
          channel_id:
            type: integer
          upgrade:
            type: boolean
            description: Upgrade the Widget to latest version of the WidgetTemplate.
      x-internal: false
  responses:
    Widget_Resp:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                $ref: '#/components/schemas/widget_Full'
              meta:
                $ref: '#/components/schemas/Meta'
          examples:
            response:
              value:
                data:
                  channel_id: 1
                  date_created: '2020-12-21T19:54:16.406Z'
                  date_modified: '2020-12-21T19:54:16.406Z'
                  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
                    name: Header Images
                    schema: []
                    storefront_api_query: ''
                    template: '{{#each images}}{{/each}}'
                    template_engine: handlebars_v3
                    uuid: f8459145-da8f-4d98-93e4-83aa47da61c6
                meta: {}
    WidgetCollection_Resp:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/widget_Full'
              meta:
                $ref: '#/components/schemas/metaCollection'
          examples:
            response:
              value:
                data:
                - channel_id: 1
                  date_created: '2020-12-21T19:54:16.406Z'
                  date_modified: '2020-12-21T19:54:16.406Z'
                  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
                    name: Header Images
                    schema: []
                    storefront_api_query: ''
                    template: '{{#each images}}{{/each}}'
                    template_engine: handlebars_v3
                    uuid: f8459145-da8f-4d98-93e4-83aa47da61c6
                - channel_id: 1
                  date_created: '2020-12-21T20:26:18.557Z'
                  date_modified: '2020-12-21T20:26:18.557Z'
                  description: ''
                  name: Simple List
                  storefront_api_query_params: {}
                  uuid: 7a842254-96ad-475f-9fe5-a59695e9685f
                  version_uuid: c23dd66b-fa3f-451d-88ef-9f4082c6051e
                  widget_configuration:
                    _:
                      id: 7a842254-96ad-475f-9fe5-a59695e9685f
                    list_items:
                    - color: blue
                      text: The color is blue
                    - color: green
                      text: The color is green
                    - color: red
                      text: The color is red
                  widget_template:
                    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
                meta:
                  pagination:
                    count: 2
                    current_page: 1
                    per_page: 50
                    total: 2
                    total_pages: 1
    Error422_Resp:
      description: 'This is the result of missing required fields, or of invalid data. See the response for more details.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_Base'
    Error404_Resp:
      description: The resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_Base'
          examples:
            example-1:
              value:
                status: 0
                title: string
                type: string
                instance: string
                errors: {}
  parameters:
    WidgetUUID:
      name: uuid
      description: The identifier for a specific widget.
      required: true
      in: path
      schema:
        type: string
        format: uuid
    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
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        | Information & Settings  | read-only  | `store_v2_information_read_only`|

        | Information & Settings  | modify     | `store_v2_information`          |


        ### 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).'
      type: apiKey
      in: header
BigCommerce Widget API

Documentation

Specifications

Other Resources

OpenAPI Specification
