> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Update Widget PUT https://api.bigcommerce.com/stores/{store_hash}/v3/content/widgets/{uuid} Content-Type: application/json Updates a **Widget**. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/content/widgets/widget/update-widget ## Authentication - `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Content | modify | `store_v2_content` | | Content | read-only | `store_v2_content_read_only` | ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes). ## Request ### Path parameters - `uuid` (string, required) — The identifier for a specific widget. - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Headers - `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. ### Body (application/json) This endpoint expects a widget_Put. - `channel_id` (integer, optional) - `description` (string, optional) — The user-friendly description. - `name` (string, optional) — The user-friendly name. - `upgrade` (boolean, optional) — Upgrade the Widget to latest version of the WidgetTemplate. - `widget_configuration` (WidgetBaseWidgetConfiguration, optional) — The JSON data that populates the template. - `widget_template_uuid` (string, optional) — The widget template UUID. ## Response ### 200 The requested widget. - `data` (widget_Full, optional) - `meta` (Meta, optional) — Response metadata. ## Errors ### 404 Not Found Error The resource was not found. - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — The error title describing the particular error. - `type` (string, optional) - `instance` (string, optional) - `errors` (ErrorBaseErrors, optional) ### 422 Unprocessable Entity Error This is the result of missing required fields, or of invalid data. See the response for more details. - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — The error title describing the particular error. - `type` (string, optional) - `instance` (string, optional) - `errors` (ErrorBaseErrors, optional) ## Types ### WidgetBaseWidgetConfiguration The JSON data that populates the template. ### widget_Full - `channel_id` (integer, optional) — The ID of the channel on which this widget exists. - `date_created` (datetime, optional) — The date on which this object was initially created. - `date_modified` (datetime, optional) — The date on which this object was last updated. - `description` (string, optional) — The user-friendly description. - `name` (string, optional) — The user-friendly name. - `uuid` (string, optional) — The primary identifier. - `version_uuid` (string, optional) — The identifier of the widget template version associated with this widget. - `widget_configuration` (WidgetBaseWidgetConfiguration, optional) — The JSON data that populates the template. - `widget_template` (widgetTemplate_Full, optional) ### Meta Response metadata. ### ErrorBaseErrors ### widgetTemplate_Full - `current_version_uuid` (string, optional) — The identifier to the current version of this widget template. - `date_created` (datetime, optional) — The date on which this object was initially created. - `date_modified` (datetime, optional) — The date on which this object was last updated. - `icon_name` (string, optional, default: default) — A read-only value. Do not attempt to set or modify this value in a POST or PUT operation. - `kind` (string, optional) — The kind of widget template. - `name` (string, optional) — The user-friendly name. - `schema` (list of WidgetSchemaItems, optional) — The schema for the widget’s merchant-facing UI. For more information on the available schema settings, see [Widget UI Schema](/developer/docs/admin/widgets-and-scripts/input-reference/schema). - `storefront_api_query` (string, optional) — The GraphQL Storefront API query that provides widget data. - `template` (string, optional) — The widget template HTML. Supports Handlebars and Paper helpers. - `uuid` (string, optional) — The primary identifier. ### WidgetSchemaItems ### widgetSchemaTab **Tab.** Use the **tab** settings type to create settings visible in Page Builder. - `type` (enum, optional) — The type of setting component to display. - Allowed values: `tab` - `label` (string, optional) — The user-friendly message to inform the user how this setting will be used. - `sections` (list of WidgetSchemaTabSectionsItems, optional) — Groups of related settings. ### widgetSchemaArray **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. - `type` (enum, optional) - Allowed values: `array` - `label` (string, optional) - `id` (string, optional) - `defaultCount` (integer, optional) — number of elements in the list to display by default. - `entryLabel` (string, optional) — name for each element in the list - `thumbnail` (WidgetSchemaArrayThumbnail, optional) — used to display an image stored at the specified attribute name - `schema` (list of WidgetSchemaArraySchemaItems, optional) — The schema used for each element in the array. ### widgetSchemaHidden **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. - `type` (enum, optional) - Allowed values: `hidden` - `settings` (list of WidgetSchemaHiddenSettingsItems, optional) ### WidgetSchemaTabSectionsItems - `label` (string, optional) — The user-friendly message to inform the user how this setting will be used. - `settings` (list of WidgetSchemaTabSectionsItemsSettingsItems, optional) — For examples of schema settings, see [Widget UI Input Types](/developer/docs/admin/widgets-and-scripts/input-reference/schema). ### WidgetSchemaArrayThumbnail used to display an image stored at the specified attribute name - `type` (string, optional) - `valueKey` (string, optional) ### WidgetSchemaArraySchemaItems ### WidgetSchemaHiddenSettingsItems For examples of each type of setting, see [Page Builder > Schema Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs. - `type` (enum, optional) — 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](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs. - Allowed values: `alignment`, `boolean`, `boxModel`, `code`, `color`, `imageManager`, `input`, `number`, `productId`, `productImage`, `range`, `regexInput`, `select`, `text`, `toggle` - `label` (string, optional) — The user friendly message to inform the user how this setting will be used. - `id` (string, optional) — The variable name where the setting value will be available in the widget template. - `default` (string, optional) — 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` (WidgetSchemaHiddenSettingsItemsTypeMeta, optional) — Additional information needed based on the selected setting type. - `conditional` (WidgetSchemaHiddenSettingsItemsConditional, optional) — 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. ### WidgetSchemaTabSectionsItemsSettingsItems For examples of each type of setting, see [Page Builder > Schema Settings](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs. - `type` (enum, optional) — 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](/developer/docs/admin/widgets-and-scripts/input-reference/schema#alignment) in Theme Docs. - Allowed values: `alignment`, `boolean`, `boxModel`, `code`, `color`, `imageManager`, `input`, `number`, `productId`, `productImage`, `range`, `regexInput`, `select`, `text`, `toggle` - `label` (string, optional) — The user friendly message to inform the user how this setting will be used. - `id` (string, optional) — The variable name where the setting value will be available in the widget template. - `default` (string, optional) — 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` (WidgetSchemaTabSectionsItemsSettingsItemsTypeMeta, optional) — Additional information needed based on the selected setting type. - `conditional` (WidgetSchemaTabSectionsItemsSettingsItemsConditional, optional) — 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. ### WidgetSchemaHiddenSettingsItemsTypeMeta Additional information needed based on the selected setting type. - `selectOptions` (list of WidgetSchemaHiddenSettingsItemsTypeMetaSelectOptionsItems, optional) ### WidgetSchemaHiddenSettingsItemsConditional 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. - `key` (string, optional) — The ID of the `settings` object the conditional attribute is related to. You must define the key within the same settings array as the conditional property to scope the conditional logic to the relevant settings group. - `operator` (string, optional) — 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`. - `value` (list of any, optional) — A single-object array containing a value from the `typeMeta`'s `selectOptions`. ### WidgetSchemaTabSectionsItemsSettingsItemsTypeMeta Additional information needed based on the selected setting type. - `selectOptions` (list of WidgetSchemaTabSectionsItemsSettingsItemsTypeMetaSelectOptionsItems, optional) ### WidgetSchemaTabSectionsItemsSettingsItemsConditional 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. - `key` (string, optional) — The ID of the `settings` object the conditional attribute is related to. The key must be defined within the same settings array as the conditional property. This ensures the conditional logic is scoped to the relevant settings group. - `operator` (string, optional) — 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`. - `value` (list of any, optional) — A single-object array containing a value from the `typeMeta`'s `selectOptions`. ### WidgetSchemaHiddenSettingsItemsTypeMetaSelectOptionsItems - `label` (string, optional) - `value` (string, optional) ### WidgetSchemaTabSectionsItemsSettingsItemsTypeMetaSelectOptionsItems - `label` (string, optional) - `value` (string, optional) ## Examples **Request** ```json {} ``` **Response** ```json { "data": { "channel_id": 1, "date_created": "2020-12-21T19:54:16.406Z", "date_modified": "2020-12-21T19:54:16.406Z", "description": "", "name": "Header Images", "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": { "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}}", "uuid": "f8459145-da8f-4d98-93e4-83aa47da61c6", "channel_id": 1, "client_rerender": false, "template_engine": "handlebars_v3" }, "storefront_api_query_params": {} }, "meta": {} } ``` **SDK Code** ```python response import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid" payload = {} headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript response const url = 'https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid'; const options = { method: 'PUT', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go response package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid" payload := strings.NewReader("{}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby response require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java response import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php response request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid', [ 'body' => '{}', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp response using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid"); var request = new RestRequest(Method.PUT); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift response import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/content/widgets/uuid")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```