Thanks for being patient while we implement your feedback to improve the developer experience.

Create a Widget

POST /content/widgets

Request

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.

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

object | application/json

  • name    string
    required

    User friendly name.

  • description    string

    The user-friendly description.

  • widget_configuration    object

    The JSON data that populates the template.

  • widget_template_uuid    string
    required

    The widget template UUID.

  • channel_id    integer

    The ID of the channel on which to create this widget. Defaults to the first channel created on the store.

example

{
  "name": "string",
  "description": "string",
  "widget_configuration": {},
  "widget_template_uuid": "string",
  "channel_id": 0
}

Response

Body

object | application/json

  • data

  • meta    object

    Response metadata.

response

{
  "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": {}
}

Get All Widgets

GET /content/widgets

Request

Returns a list of Widgets. Optional parameters can be passed in.

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.

  • 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.

  • widget_template_uuid in query - string

    The identifier for a specific widget template.

  • name in query - string

    The URL encoded name of the widget.

  • name:in in query - array

    Use to pass in comma-separated list of widget names. Example: /widgets?name:in=test-widget-name,header%20images

  • channel_id:in in query - integer

    Filter items by channel_id.

  • site_id:in in query - string

    A comma-separated list of site ids to filter the results by.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/content/widgets' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

  • data    array[object]

  • meta    object

    Data about the response, including pagination and collection totals.

response

{
  "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
    }
  }
}

Get a Widget

GET /content/widgets/{uuid}

Request

Returns a single Widget.

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 widget.

example

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

Response

Body

object | application/json

  • data

  • meta    object

    Response metadata.

response

{
  "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": {}
}

Update a Widget

PUT /content/widgets/{uuid}

Request

Updates a Widget.

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.

  • description    string

    The user-friendly description.

  • widget_configuration    object

    The JSON data that populates the template.

  • widget_template_uuid    string

    The widget template UUID.

  • channel_id    integer

  • upgrade    boolean

    Upgrade the Widget to latest version of the WidgetTemplate.

    example

    {
  "name": "string",
  "description": "string",
  "widget_configuration": {},
  "widget_template_uuid": "string",
  "channel_id": 0,
  "upgrade": true
}

    Response

    Body

    object | application/json

    • data

    • meta      object

      Response metadata.

    response

    {
  "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": {}
}

    Delete a Widget

    DELETE /content/widgets/{uuid}

    Request

    Deletes a Widget.

    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 widget.

    example

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

    Response

    An empty response.