> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Subscription Versioning
> Manage subscription changes with version control
# Subscription Versioning
Subscription versioning allows you to make changes to subscriptions that take effect at a specific date while maintaining a complete history of all changes. This is essential for handling upgrades, downgrades, renewals, and mid-cycle changes.
***
## What Is Versioning?
Every subscription can have multiple versions representing its state at different points in time:
```mermaid theme={null}
graph LR
A[Version 1
Jan 1 - Mar 31
Starter Plan] --> B[Version 2
Apr 1 - Dec 31
Pro Plan]
B --> C[Version 3
Jan 1 - ...
Enterprise Plan]
```
Each version contains:
* Products and pricing
* Contract terms
* Billing configuration
* Effective date range
***
## Version States
| State | Description |
| -------------------- | ------------------------------------------- |
| **Draft** | Being configured, can be edited |
| **Pending Approval** | Awaiting approval (if approval rules apply) |
| **Published** | Approved, waiting for effective date |
| **Active** | Currently in effect |
| **Superseded** | Replaced by newer version |
***
## Creating a New Version
1. Navigate to **Subscriptions → \[Subscription]**
2. Click **Create New Version** or **Edit Subscription**
3. Make your changes:
* Add, remove, or modify products
* Adjust quantities or pricing
* Update contract terms
4. Set the **Effective Date**:
* **Immediate**: Changes apply now
* **End of Period**: Changes apply at next renewal
* **Custom Date**: Select a specific future date
5. Review the proration preview (if applicable)
6. Click **Save as Draft** or **Publish**
Save as draft if you need to review changes before they take effect. Publish when ready to commit the changes.
***
## Managing Versions
### View Version History
1. Navigate to **Subscriptions → \[Subscription]**
2. Click **Version History** tab
3. See all past, current, and scheduled versions
4. Click any version to view details
### Edit a Draft Version
1. Open the draft version from version history
2. Make changes
3. Save or publish
### Cancel a Scheduled Version
1. Find the published (scheduled) version
2. Click **Cancel Version**
3. Confirm cancellation
The subscription will continue on its current version.
***
## Common Use Cases
### Customer Upgrade
1. Customer wants to upgrade from Starter to Pro
2. Create new version with Pro plan
3. Set effective date (immediate or end of period)
4. Publish - proration is automatically calculated
### Annual Renewal with Price Change
1. Customer's annual subscription is renewing
2. Create new version with updated pricing
3. Set effective date to renewal date
4. Publish to schedule the change
### Add Product to Existing Subscription
1. Customer wants to add an add-on product
2. Create new version
3. Add the new product as a line item
4. Set pricing and effective date
5. Publish
### Contract Amendment
1. Customer negotiates different terms
2. Create new version with updated contract terms
3. Get approval (if approval rules apply)
4. Publish when approved
***
## Ramps and Phases
For enterprise contracts, you can set up **pricing ramps**—scheduled price changes that take effect at specific dates throughout the contract term.
### What Are Ramps?
Ramps allow you to define pricing that changes over time, commonly used for:
* **Annual escalators**: 5-10% yearly price increases
* **Phased rollouts**: Lower pricing during pilot, full pricing at scale
* **Growth pricing**: Pricing that matches expected customer growth
* **Commitment discounts**: Lower year-1 pricing that normalizes in later years
### Example: 3-Year Enterprise Contract
| Phase | Dates | Monthly Price | Reason |
| ------ | ------------------- | ------------- | ------------------ |
| Year 1 | Jan 2024 - Dec 2024 | \$5,000 | Pilot discount |
| Year 2 | Jan 2025 - Dec 2025 | \$8,000 | Full rollout |
| Year 3 | Jan 2026 - Dec 2026 | \$8,400 | 5% annual increase |
### Setting Up Ramps
1. Navigate to the subscription or quote
2. Add products and set Year 1 pricing
3. Click **Add Phase** or **Schedule Price Change**
4. Set the effective date for the next phase
5. Enter the new pricing for that phase
6. Repeat for additional phases
7. Save or publish
Each phase appears as a scheduled version that will automatically activate on its effective date.
### Viewing Scheduled Phases
1. Go to **Version History** on the subscription
2. See all scheduled versions with their effective dates
3. Each phase shows its pricing configuration
4. Modify or cancel scheduled phases as needed
***
## Version Comparison
Compare two versions to see differences:
1. Go to **Version History**
2. Select two versions to compare
3. View side-by-side comparison of:
* Products and quantities
* Pricing changes
* Contract term differences
***
## Approval Workflow
If approval rules are configured, versions requiring approval will:
1. Enter **Pending Approval** state when published
2. Notify assigned approvers
3. Wait for approval before becoming active
4. Can be edited or canceled while pending
***
## Best Practices
Save complex changes as draft to review before publishing.
Choose effective dates that align with billing cycles when possible.
Check the proration preview before publishing mid-cycle changes.
Add notes to versions explaining why changes were made.
***
## Next Steps
Learn about subscription amendments.
Understand proration calculations.