Executing a price change

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 matrix cells on a matrix 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 webapp 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. 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.
• 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.

Invoices generated by plan versioning

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.

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, there are a few ways that a subscription's set of prices may deviate from the plan it's subscribed to:

• When creating the subscription, Orb allows you to override specific aspects of the subscription's pricing configuration such as the price point of individual prices. Under the hood, this creates a new plan altogether, sometimes termed a "child plan". Migrations are not yet compatible with these overrides plans and these subscriptions will be left unaffected by a migration. In order to migrate these to the latest version, perform a plan change to the same plan (which will then move the subscription to the latest version) and specify which overrides are required manually. Orb will always move the subscription to the default version of the plan.
• 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.
• 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 architected, migrations are fully protected from billing period related timing race conditions even when they are not fully processed.

When a migration is scheduled for a set of subscriptions, Orb ensures correctness: even if it's a "last minute" action before the end of the billing period, Orb will ensure that the new version's prices will be accurately reflected. Orb will apply the migration during the process of issuing an invoice if required, making sure that the old prices are never reflected past the effective date of a migration.

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.

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.