Modifying subscriptions

Orb has powerful support to modify ongoing subscriptions, giving you the flexibility to model complex billing behavior while still maintaining granular control of invoicing behavior.

Adding a new price

You can add individual prices to Orb subscriptions at any time. This can be used to easily model feature add-ons, where customers can opt in or out of paying for additional features, or to add new SKUs to subscriptions as your pricing evolves. You can add a price to a subscription using the subscription price intervals API.

For example, imagine that you’re a web hosting provider billing your customers monthly, and you want to allow users to start using a new optional storage feature and bill them for their usage. With Orb’s API, you can add a new price called “Storage (Gb)” to the subscription starting at the beginning of the month. This will charge the customer on their end of month invoice for any usage of the storage feature in the current month — removing the need to wait for the end of a billing cycle to start billing for a new service.

You can also add prices starting in the future, allowing you to stage price changes in advance. For example, this allows you to add prices starting at the beginning of the next billing cycle and preview how they’ll look on invoices before customers see any changes to their subscription or pricing.

Removing a price

Both add-on and plan prices can also be removed from a subscription using the subscription price intervals API. This can be used to model cancellation of feature add-ons or allow customization of individual subscriptions based on changing terms.

For example, imagine you’re the same web hosting provider, and you want to allow your customers to optionally pay a fixed fee to get access to advanced metrics. With Orb’s API, you can add this fee whenever in the billing cycle the user opts in to the advanced metrics feature, which will charge the customer a prorated amount for the remainder of the monthly billing period. Then, if the customer wants to cancel their advanced metrics add-on, you can edit the price’s end time to the end of the monthly billing period using the Orb API, which will ensure that the customer is not charged again for the add-on.

Changing an existing price

You can also use a combination of price removals and additions to flexibly change prices over time without disruptions to normal invoicing behavior. For example, imagine you want to increase a price for a subset of customers starting at the beginning of the next billing cycle. With the subscription price intervals API, you can set the current plan price to end at the end of the current billing period, and add a new, edited version of the price to the subscription starting at the end of the current billing period. This will result in a price change at the next billing period boundary without issuing additional invoices.

For example, in the scenario below, we’re replacing Notifications delivered with an updated version of the price without issuing additional invoices.

Changing a fixed fee quantity

You can also change the quantity to charge for a fixed fee at any time, past or future. For example, imagine that you charge a fixed fee for seats in addition to usage. If a customer wants to increase their number of seats, you can use the Orb API to initiate an immediate change to the price’s quantity. This will generate an invoice for the price of the additional seats, prorated to the remaining duration of the billing period.

If you didn’t want to prorate seat purchases, you could instead use the Orb API to change the fixed fee quantity effective at the start of the billing cycle. This would result in an invoice being issued for the price of the seats without proration.

You also might want to schedule fixed fee quantity changes for the future to avoid generating additional invoices, or to model things like purchasing plans. For example, imagine the customer’s current seat count is 5, and they wanted to increase their seat count to 10 next month and 20 in two months. You could use the Orb API now to schedule these fixed fee quantity changes on billing period boundaries in the future, which will add these additional seats to the invoices that will already be issued at the billing period boundary.

Subscription plan changes

As your customer continues using your product, they may choose to change their level of service, requiring a change to their billing configuration. This is most common when a customer is either upgrading or downgrading plans, but can also be necessary when any pricing terms durably change (e.g. the addition of a new usage metric to an existing plan, or a new signed commitment requiring a minimum to be added to the plan).

When you execute a subscription change, Orb internally versions the Subscription, and continues to provide an audit trail of the previous state and plans of the Subscription. Since Orb’s invoices always correspond to a single plan, so a plan change may result in two invoices being issued: an invoice with charges on the old plan, as well as an up-front invoice for the new plan.

Prorations for in-advance fees

If a plan change is for a customer that has already paid an in-advance fee, Orb will credit the customer an amount corresponding to the portion of the time period that was left unused using day-based proration. This amount will be added to the customer balance, which will be used by future invoices.

Consider the following plans table:

Plan Name	In advance fee
Beginner	$50
Intermediate	$100
Advanced	$500

The following timeline illustrates the prorations, assuming that all subscriptions bill on the first of the month and prorate accordingly:

Date	Manual actions	Orb behavior
07-01-2023	Subscription started to Intermediate	Orb issues an invoice for $100.
07-04-2023	Changed from Intermediate to Advanced	Orb issues an invoice for any usage accrued on Intermediate. Orb issues a credit note on the 07-01-2023 invoice to refund for 28 days that were not used on Intermediate ($90.32). Orb issues an invoice for 28 days of utilization of Advanced ($451.61), and utilizes the full customer balance to charge $361.29.
07-11-2023	Changed from Advanced to Beginner	Orb issues an invoice for any usage accrued on Advanced. Orb credits the customer balance for 21 days that were not used on Advanced, out of the original 28 days paid ($338.71). Orb issues an invoice for 21 days of utilization of Beginner ($33.87), and draws down the customer balance to charge $0. The remaining customer balance is $304.84.

Scheduling plan changes

Orb’s web application supports changing a subscription’s plan immediately, on a requested future date (e.g. the start of a new contract), or at the end of the subscription’s current term (e.g. if the term represents a customer's current commitment). This also provides an opportunity to change the subscription’s billing date, which can be modified to be the start of the new plan.

Once a plan change has been scheduled, Orb will honor the change over any scheduled cancellations.