As your monetization strategy evolves, so will the items and price points on your standardized plans. Orb solves this change management problem in a safe and predictable way by introducing the concept of a plan “version” and a “subscription migration”, which allows you to apply that version across a set of selected subscriptions. This is significantly more auditable than simply editing plans “in-place”, which creates data reconciliation problems down the line. Orb’s plan versioning feature is built on top of a few core principles:

1. Safety through clarity: At each part of the flow, Orb allows you to preview the effect of your changes. In the process of creating a new plan version, Orb will display a clear difference view to indicate the prices that have been removed, added, or changed. When configuring a migration, Orb will allow you to preview the effect of the migration for individual customers.
2. Flexibility in scheduling: Orb’s invoicing backend is built to allow changes at any time in the future, immediately, or even in the past. Once scheduled, changes will apply without any manual intervention required.
3. Simplicity for the end-user: Orb’s migrations functionality is specifically built to minimize the number of issued invoices which would create confusion for your end-users, and support requests for your team. For example, Orb supports changes ‘at the end of the billing cycle’, even if it’s different for each user. Adding a new in-arrears usage based fee will automatically be consolidated with other fees that bill on the same cadence. Adding a new in-advance fee will bill for only that fee independently, and not fracture the entire subscription.
4. Automation at scale: Orb’s migration functionality has been battle-tested over millions of subscriptions, and is built to handle both enterprise and self-serve use cases.

​

Version 1

When you create a plan, the set of prices included in the plan will become your first version of the plan, that is: Version 1. When you publish your new plan, Version 1 will become the default version which means all new subscriptions created via the web or the API will use these price points.

​

Creating a new plan version

Each subscription in Orb is subscribed to a single version of a plan; namely, the version that was marked as the default version when the subscription was created. At any given time, there may be thousands of subscriptions subscribed to a plan, some on different plan versions. In order to edit a plan’s prices, you’ll need to create a new version that reflects those changes by selecting “Add version” on the plans page. Note that metadata edits (name and description) do not require a new version and are scoped to the Plan as a whole. You can edit these by selecting “Edit name and description” on the plan page. In Orb, you have a linear series of versions — each version builds on the last, so you’ll always edit the most recent version to create a new one. Plan versions are identified by an increasing set of integer version numbers. When you create a new version you can:

• Add a price: You can add a new price to the existing plan version. For example, you’d opt to do this if you’re planning to roll out a new default-on usage-based SKU to everyone on your “Pro” tier, such that any usage that is now sent for that SKU into Orb should accrue on the relevant invoices.
• Edit a price: This is the most common action in order to change parameters of your pricing — this may range from changing the unit price point, adding or removing tiers, or modifying the dimension values on a dimensional price. Although editing a price is functionally similar to removing followed by adding a price, Orb understands the concept of replacing explicitly. This is particularly helpful in the presence of subscriptions where a price has later been removed through an edit action. Because Orb understands that your versioning action is a replacement, the system will not re-add the price and will leave it removed.
• Remove a price: Removing a price can be useful if you no longer want to charge for an item on your plan.
• Edit details: You can also modify the maximums, minimums and discounts that are already on your plan. We recommend reviewing these when you change prices to make sure they’re still applicable.

​

Publishing a version

After your version is reviewed and ready, you can publish the new version. When you publish the version, you have the option to make the new version Default or leave the existing default. When you make a new version the default, all new customers who subscribe to this plan will automatically be attached to these prices. Note that this is true of subscriptions created both via the Orb web-app as well as those created via the API, through any automations you have configured. This never affects existing subscriptions; in order to change prices for existing subscriptions you must migrate them to the new version (explained below).

​

Alerts and Versioning

When you create a new plan version, Orb will automatically copy over alerts that were previously configured on prices that have not been edited or removed on the new version. If a price point has been edited or the price has been entirely removed, alerts will no longer trigger for subscriptions to the new version. You can and should modify your alerts before migrating any subscriptions over to your new plan version. Once a subscription is migrated to the new version, the new plan version alerts will be applied to the subscription. Orb will indicate if alerts were copied with a hint next to the Alerts tab.

​

Migrating subscriptions to a new version

Although publishing a version does not affect existing subscriptions, Orb allows you to mass-schedule these migrations without having to write any scripts, saving you time and the risk of incorrectly applied migrations. Orb allows you to migrate a subscription from one version to another with the following timing options, detailed below:

• Immediately: The new version’s set of prices will begin immediately and any existing prices from the old version will be ended. Since Orb uses day-based proration, immediate changes will take effect as of the beginning of the day in the customer’s timezone for fixed fees, and lead to an immediate cutoff for usage-based fees. This will likely lead to the generation of a new invoice for each affected subscription, typically representing the accrual of any usage-based charges for the previous version and any newly added in-advance fees. Note, of course, that grace period allowances still apply before the invoice is issued.
• End of term: This option takes advantage of the fact that Orb knows the billing period of each price across all your individual subscriptions. When this option is selected, the timing may vary for each subscription depending on its bill cycle day and cadences. The term is the maximum cadence across all the prices on the subscription — so Orb will not migrate the subscription until the term fully rolls over. In the typical scenario with only monthly prices, Orb will migrate the subscription at the end of its billing month, which may or may not align with the calendar month.
• Beginning of term: Similar to end of term, this option uses the price billing periods of each individual subscription to backdate a migration to the beginning of the subscription’s current term (the start of the current billing period for the price with the largest cadence). In the typical scenario with only monthly prices, Orb will migrate the subscription at the beginning of its billing month, which may or may not align with the calendar month. This option allows you to change your pricing in the middle of the billing period without issuing unexpected invoices — for example, if you’re billing monthly and want to launch a feature mid-month, you can just roll out the feature immediately and migrate subscriptions using the beginning of term option anytime in the month, and all of the usage of the new feature will be included in the end-of-month invoice.
• Specific date: Similar to ‘immediately’, Orb will start and end prices as of the selected date. Orb recommends using this if you have a communicated change date in marketing material.

Orb allows you to review the migration action in detail, both reviewing the aggregate action (e.g. number of subscriptions affected) as well as previewing how the migration will affect any given customer. Orb recommends that you spot-check individual customers to understand and confirm the effect of the migration. When a migration is scheduled, Orb provides a cancellation grace period before taking any action. During the grace period, the migration can be completely aborted without any consequences. Once the grace period elapses, Orb takes action by triaging each subscription and reflecting the new state. This happens regardless of the scheduled timing of the actual migration, because even future-changes must be reflected immediately on all subscriptions. This is an important property of the Orb system, and creates a predictable product experience. For example, when viewing a subscription’s timeline or upcoming invoice, it’s important that the future migration is properly accounted for. Once a migration has been reflected across all subscriptions, Orb does not perform any mass action at the time of the migration itself — this is already handled when the migration is first created.

​

Invoicing consequences of plan version migrations

Unlike a plan change where prices are always fractured at time of plan change, Orb factors in prices that have not been changed when a subscription is migrated in order to avoid invoicing for that price unnecessarily. For example, if a single usage-based price is added in the new version, it will automatically align to the billing cadence of other prices and no prices will invoice when the migration is applied. Similarly, if only an in-advance fixed fee is added in the new version, that fee alone will invoice without causing disruptions to the billing periods of other usage-based or fixed-fee prices. In general, end of billing period pricing changes are the safest option, as they will never cause additional invoices to be generated. The table below shows the invoicing effect of different pricing change migrations depending on when in the billing period the migration is applied. A change to an existing price in a new version can be thought of as a removal of the old price and an addition of the new price.

Pricing Change	Migration Timing	Invoicing Impact
Add usage-based price	Immediate	The new price starts accounting for usage immediately and will invoice with other usage-based fees at the end of the billing period. No additional invoice generated.
Add usage-based price	End of term	The new price starts accruing at the beginning of the next billing period. No additional invoice generated.
Add usage-based price	Beginning of term	The new price starts accruing from the start of the current billing period. Usage for the entire period will be included in the next invoice. No additional invoice generated.
Remove usage-based price	Immediate	The old price will invoice immediately from the start of the billing period until the current time.
Remove usage-based price	End of term	The old price will invoice until the end of the current billing period.
Remove usage-based price	Beginning of term	The old price will invoice until the start of the current billing period.
Add in-advance fixed fee	Immediate	A new invoice will be generated immediately for the prorated amount of the new fixed fee for the remainder of the current billing period.
Add in-advance fixed fee	End of term	The new fee will be charged in full at the start of the next billing period. No additional invoice generated.
Add in-advance fixed fee	Beginning of term	A new invoice will be generated dated to the start of the billing period to charge the full amount of the new fixed fee.
Remove in-advance fixed fee	Immediate	The fixed fee will be removed from the subscription and a credit note will be applied to the invoice issued at the beginning of the billing period to prorate the fixed fee. No additional invoice generated.
Remove in-advance fixed fee	End of term	The fixed fee will be removed from the subscription at the end of the current billing period. No additional invoice generated.
Remove in-advance fixed fee	Beginning of term	The invoice at the start of the current billing period will be voided and a new one will be generated in its place without the removed fixed fee.
Add in-arrears fixed fee	Immediate	The new fixed fee will be added to the subscription and a prorated amount will be invoiced for it at the end of the billing period. No additional invoice generated.
Add in-arrears fixed fee	End of term	The new fixed fee will be added to the subscription at the end of the current billing period. No additional invoice generated.
Add in-arrears fixed fee	Beginning of term	The new fixed fee will be added to the subscription at the start of the current billing period and will invoice at the end of the billing period. No additional invoice generated.
Remove in-arrears fixed fee	Immediate	The fixed fee will invoice immediately prorated from the start of the billing period until the current time.
Remove in-arrears fixed fee	End of term	The fixed fee will be removed from the subscription at the end of the current billing period. No additional invoice generated.
Remove in-arrears fixed fee	Beginning of term	The fixed fee will be removed at the start of the current billing period. No additional invoice generated.

​

What does not change in a migration

When migrating plans to a new version, Orb does not modify the following fields in the creation flow. These are also disabled in the plan creation flow in the UI.

• Currency
• Custom pricing units
• External plan ID
• Net payment terms
• Plan name
• Plan description

​

Subscription changes after a migration is scheduled

If you schedule a migration for a subscription and then subsequently change the plan or cancel the subscription, the price change will be overwritten. The latest action you take is always the one that is maintained. The current state of a subscription is displayed in the timeline of the customer page. As an example: if you schedule a price change on 4/1 that should take effect at the end of term on 4/15 and you cancel the subscription on 4/10, then Orb will cancel the subscription and no price change will occur on 4/15.

​

Migrating non-standard subscriptions

In Orb, a subscription’s set of prices can deviate from the plan it’s subscribed to for a variety of reasons, which will impact the behavior of a plan version migration.

​

Subscription overrides

Override action taken	Change in new plan version	Migration behavior
Price A overridden, replaced with Price X	Price A replaced with Price B	Price X will remain on the subscription unchanged
Price A overridden, replaced with Price X	Price A removed	Price X will remain on the subscription unchanged
Price A overridden, replaced with Price X	Price C added to the subscription	Price C will be added to the subscription, Price X remains unchanged
Price A removed	Price A replaced with Price B	Price B will not be added to the subscription

​

Example: Subscription overrides

Consider a plan with two prices:

• Price A: A usage based fee charging on the number of API requests
• Price B: A fixed fee charging for a seat-based charge

If a subscription is created with the following overrides:

• Price A is kept the same
• Price B is removed entirely
• Price C is added as a new fixed fee

When the plan is updated with a new version that:

• Replaces Price B with Price X

Price X will not be added to the subscription, as Price B was overridden and removed. Price A will remain unchanged, and Price C will remain on the subscription.

​

Add-ons

After a subscription has been created, it can be edited with a subscription edit (which allows you to add/remove prices). This does not change the plan that the subscription is attached to. Migrations can be applied to subscriptions with edits, and Orb will automatically resolve the behavior in the presence of these edits. For example, if a price has been changed that is no longer on the relevant subscription, it will be unaffected. Similarly, add-ons that have been individually added to a subscription will not be removed even if that add-on is not explicitly in the new plan version, and plan prices that have been removed with subscription edits will not be added back to the subscription if modified in a new plan version.

​

Fixed-fee quantities

It’s possible that fixed-fee quantities have changed on the subscription, independent of the default on the plan. If the same fixed-fee is present on the new plan version or the rate of the fixed fee has been changed, the quantity schedule will carry over untouched.

​

Migration correctness and timing

A migration can take many hours to fully complete processing all subscriptions – typically, migrations will process at around 2 seconds per subscription. However, because of the way they are designed, migrations are fully protected from billing period related timing race conditions even when they are not fully processed.

​

Plan versioning workflows with webhooks

In order to build custom workflows with plan versioning, Orb will issue a series of webhooks for each subscription – listen to the subscription.plan_version_change_scheduled and subscription.plan_version_changed webhooks to react to version changes in your own application.

​

Plan changes vs. versioning

Ask yourself whether your customers would think of the change you’re planning as a “new service contract”, or whether it’s an iteration on your existing feature-set and price points. If the latter, plan versioning and migrations is an appropriate fit. If your use case truly represents an entirely new packaging (e.g. going from 2 packages to 4 packages), Orb recommends treating the new packages as net-new by creating new plans. Instead of versioning your plan, it’s also possible to copy the current plan to a new plan and use plan changes to move customers to the new copy.

​

Threshold Invoicing

When a plan version migration adds, removes, or alters a price—whether immediately or as a backdated action—some threshold invoices may become orphaned. These orphaned invoices will still be visible to users in the invoicing portal but will be linked to a credit note if any of their prices are affected by the plan change. Any new threshold invoices created before the end of the billing period will be offset by the balance from the credit notes. If you do not check the box labeled “Allow Orb to correct past invoices and issue credit notes” when starting a migration, Orb will fail to migrate the subscription rather than attempt to orphan a threshold invoice.

​

Canceling a migration

If a migration is canceled during the grace period of 5 minutes, no action is performed. If the grace period has elapsed, canceling a migration will prevent new subscriptions from being put in a ‘scheduled’ state. However, this does not automatically revert any scheduled migrations in the future, as those upcoming changes have already been reflected on each subscription’s timeline. In order to do so, you can schedule a new migration back to the original version.

​

Migration checklist

Migrations are a powerful tool to make changes across your entire customer base, and we recommend a careful approach to executing them. Consider the following questions before running your migration:

1. Ensure that the effective time of your migration is what you intend. The effective time can have major consequences on whether invoices will issue. Especially if you have prices on your subscription with multiple cadences, remember that the ‘term’ concept refers to the price with the longest cadence (so a start or end of term may be up to a year in the past or the future).
2. Be sure to understand the invoices or credit notes that will change as the result of your migration. Orb allows you to inline preview these changes when staging the migration on a per-customer basis.
3. Consider how different subscriptions may migrate differently. We recommend that you check subscriptions that have custom adjustments (i.e. those that have been added directly to the subscription), subscriptions on different phases (if your plan is phased), and subscriptions that may have had prices replaced, removed, or added.