> ## Documentation Index
> Fetch the complete documentation index at: https://docs.variable.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Product and material versioning

> Managing version states, creating new versions, and understanding syncId preservation

Versioning in Variable allows you to maintain a history of your products and materials while ensuring data integrity. This is essential for tracking changes over time, maintaining audit trails, and supporting collaborative workflows.

## Version states

Products and materials can exist in one of three version states:

| State        | Editable | Description                                     |
| :----------- | :------- | :---------------------------------------------- |
| **Draft**    | Yes      | Work in progress, can be modified               |
| **Locked**   | No       | Finalized version, immutable                    |
| **Verified** | No       | Third-party validated, highest confidence level |

```mermaid theme={"system"}
stateDiagram-v2
    [*] --> Draft: Create new
    Draft --> Draft: Edit
    Draft --> Locked: Lock version
    Locked --> Draft: Create new version
    Locked --> Verified: Third-party validation
```

<Note>
  Once a product is locked, its data cannot be changed. This ensures that any references to that version (in other products, reports, or external systems) remain consistent.
</Note>

## Version life-cycle

### 1. Create draft

When you create a new product or material, it starts as a draft:

* Fully editable
* Changes save automatically
* Not visible to external references by default
* Can be deleted without impact

### 2. Edit and refine

While in draft state:

* Add and modify inputs
* Adjust quantities and datasets
* Update metadata (name, description, taxonomy)
* Review calculated impacts
* Make as many changes as needed

### 3. Lock version

When you're satisfied with the product:

* Lock the version to make it immutable
* Locked versions get a version number (1, 2, 3...)
* The product becomes available for use in other products
* External systems can reference it with confidence

<Warning>
  Locking is permanent for that version. You cannot unlock a version. If changes are needed, create a new version instead.
</Warning>

### 4. Create new version

When updates are required:

* Create a new draft from the locked version
* The new draft copies all data from the locked version
* Edit the new draft as needed
* Lock when ready to create the next version

## Verifying a version

A locked version can be **verified** — an independent sign-off that the version has been reviewed and can be trusted. Verified is the highest-confidence state, signaling third-party validation rather than just finalization.

Verification is carried out by a team member with the **Verifier** role, who has read-only access plus this one capability. Only locked versions can be verified, and verifying never changes the underlying data — it records the sign-off, with an optional note, in the audit history. Verified versions keep their version number and stay immutable.

To verify a version in the Variable app, open the version and choose **Mark as verified**. Verification is available for any product or material that supports versioning.

## syncId preservation

The `syncId` is a stable identifier that persists across versions:

| Property  | Behavior across versions           |
| :-------- | :--------------------------------- |
| `uuid`    | Changes with each version          |
| `syncId`  | Stays the same across all versions |
| `version` | Increments (1, 2, 3...)            |

```mermaid theme={"system"}
flowchart TB
    subgraph "Product: Steel Bracket"
        V1[Version 1<br/>uuid: abc-123<br/>syncId: bracket-001]
        V2[Version 2<br/>uuid: def-456<br/>syncId: bracket-001]
        V3[Version 3<br/>uuid: ghi-789<br/>syncId: bracket-001]
    end
    V1 --> V2 --> V3
```

<Info>
  Use `syncId` when you need to track an item across versions in external systems (ERP, PLM). The `uuid` identifies a specific version, while `syncId` identifies the logical item regardless of version.
</Info>

### syncId rules

* Must be unique across your organization
* Can be set during creation
* Persists through version creation
* Should be treated as a stable identifier for external integrations
* Changing it can impact downstream system mappings and references

## When to create a new version

Create a new version when:

| Scenario              | Action      | Why                                  |
| :-------------------- | :---------- | :----------------------------------- |
| Material data updated | New version | Preserve historical footprint values |
| Supplier changed      | New version | Traceability for sourcing changes    |
| Process improved      | New version | Track improvement over time          |
| Error correction      | New version | Audit trail of corrections           |
| Annual update         | New version | Maintain time-series data            |

Keep editing the current draft when:

| Scenario           | Action     | Why                       |
| :----------------- | :--------- | :------------------------ |
| Initial data entry | Edit draft | Not yet ready for use     |
| Typo in name       | Edit draft | No impact on calculations |
| Still under review | Edit draft | Not finalized             |

## Version visibility

Control who can see and use different versions:

| Visibility          | Access                                 |
| :------------------ | :------------------------------------- |
| Private             | Only your organization                 |
| Link                | Anyone with the direct link            |
| API                 | Accessible via API with authentication |
| Authenticated users | All logged-in Variable users           |

<Note>
  Locked versions are typically set to appropriate visibility for their intended use. Draft versions are usually kept private until ready.
</Note>

## Working with versions in the API

### Get latest version

```bash theme={"system"}
GET /v1/product?syncId=bracket-001
```

Returns the most recent version of the product with that syncId.

### Get specific version

```bash theme={"system"}
GET /v1/product/{uuid}
```

Returns the exact version identified by uuid.

### Create new version

Creating a new version from an existing locked product:

1. Retrieve the locked product
2. Create a new product with the same syncId
3. The new product starts as a draft with version number incremented

## Best practices

1. **Lock before sharing** - Don't share draft versions externally; lock first to ensure stability.

2. **Document changes** - Use the description or notes field to explain what changed between versions.

3. **Regular reviews** - Set up periodic reviews to update products with new supplier data.

4. **Version alignment** - When updating a product, consider whether component materials also need new versions.

5. **Clean up drafts** - Delete abandoned drafts to keep your inventory tidy.

6. **Use syncId consistently** - Map syncId to your internal part numbers for seamless integration.

## Related topics

* [Products & Materials](/docs/material) - Product structure and attributes
* [syncId](/docs/syncId) - External identifier details
* [Data quality ratings](/docs/help/data-quality) - Quality tracking across versions