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

# Widget Versioning

Plan: Stencil Developer

Lesson 12 of 22 · 30 min

Widget versioning allows developers to release updates to widget templates without impacting existing widgets created using those templates.

A single widget template can have multiple versions, each with its own *template* and *schema* properties. The widget template's `current_version_uuid` property points to the most recent version of the widget template. When you create a widget, it automatically uses the most current version of the widget template and saves it as the `version_uuid` property.

## Old Relationship Model

Prior to widget versioning, a widget would point to a widget template only via the `widget_template_uuid` property. The widget would always use the latest version of the widget template, and updating the widget template would subsequently update all of its widgets.

![Old Relationship Model](/_fern-files/bigcommerce.docs.buildwithfern.com/668b4d103202b56d1c30ea68bc5d711c10e33e69ee12bac95a24aa65b12e85f8/assets/learn/widgets-rest-api/widgets-overview-01.png)

## New Relationship Model

Widget versioning introduced `current_version_uuid` and `version_uuid` properties. Now, in addition to `widget_template_uuid`, the widget can specify the template version via the `version_uuid` property.

![New Relationship Model](/_fern-files/bigcommerce.docs.buildwithfern.com/4ee436dead04448b0166b1a25761b9ae73ec3530d5b8c1b8af467564328a1c31/assets/learn/widgets-rest-api/widgets-overview-02.png)

> **Info**
>
> Although a widget template can have multiple versions, there can only be one active version at a time. This setup means that a template can have multiple `version_uuid` values associated with it, but it cannot have more than one `current_version_uuid` value.

### Widget template definitions

| **Property**             | **Definition**                                                    |
| ------------------------ | ----------------------------------------------------------------- |
| *uuid*                   | The identifier of the original widget template.                   |
| *current\_version\_uuid* | The identifier of the most recent version of the widget template. |

### Widget definitions

| **Property**                      | **Definition**                                                          |
| --------------------------------- | ----------------------------------------------------------------------- |
| *widget\_template\_uuid    * | The identifier of the widget template. (The value is static.)           |
| *current\_version\_uuid    * | The identifier of the most recent version of the widget template.       |
| *version\_uuid*                   | The version of the widget template used to create or update the widget. |

## Update a Widget Template

To update a widget template without impacting existing widgets, set the `create_new_version` property to *true* when sending a *PUT* request to [*/v3/content/widget-templates/\{uuid}*](/developer/api-reference/rest/admin/content/widgets/widget-template/update-widget-template). This will create a new widget template version, but it will not impact the widgets created before the update.

Updating the widget template with `create_new_version` set to *true* will change the value of the `current_version_uuid` in the widget and the widget template, but it will not change the value of the widget's `version_uuid`.

> **Info**
>
> It is possible to update your widget template without creating a new version. To do so, exclude the create\_new\_version field or set it to false when making a PUT request to [**update the widget template**](/developer/api-reference/rest/admin/content/widgets/widget-template/update-widget-template).