BigCommerce
Theme & Content APIs
Widget Template

Widgets

Create a Widget Template

POST /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
  • 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

Response

Body

application/json
  • data

  • meta
    object

    Response metadata.

    response

    Get All Widget Templates

    GET /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

    Response

    Body

    object | application/json
    • data
      array[object]

    • meta
      object

      Data about the response, including pagination and collection totals.

    response

    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 - 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_configuration
      object

      The JSON data that populates the template.

    example

    Response

    Success

    Body

    object | application/json
    • data

    example

    Get a Widget Template

    GET /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

    Response

    Body

    application/json
    • data

    • meta
      object

      Response metadata.

      response

      Update a Widget Template

      PUT /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
      • 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

        Response

        Body

        application/json
        • data

        • meta
          object

          Response metadata.

          response

          Delete A Widget Template

          DELETE /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

          Response

          An empty response.

          Did you find what you were looking for?