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 |
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.
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
Locking is permanent for that version. You cannot unlock a version. If changes are needed, create a new version instead.
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…) |
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.
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 |
| 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 |
Locked versions are typically set to appropriate visibility for their intended use. Draft versions are usually kept private until ready.
Working with versions in the API
Get latest version
GET /v1/product?syncId=bracket-001
Get specific version
Returns the exact version identified by uuid.
Create new version
Creating a new version from an existing locked product:
- Retrieve the locked product
- Create a new product with the same syncId
- The new product starts as a draft with version number incremented
Best practices
-
Lock before sharing - Don’t share draft versions externally; lock first to ensure stability.
-
Document changes - Use the description or notes field to explain what changed between versions.
-
Regular reviews - Set up periodic reviews to update products with new supplier data.
-
Version alignment - When updating a product, consider whether component materials also need new versions.
-
Clean up drafts - Delete abandoned drafts to keep your inventory tidy.
-
Use syncId consistently - Map syncId to your internal part numbers for seamless integration.
