Skip to main content
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, 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.
Subscription history is preserved: When you change plans, the subscription ID remains the same, but Orb maintains a complete audit trail of every plan assignment. This allows you to see what plan a customer was on at any point in time and ensures accurate billing and revenue recognition.
plan-change.png

​
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.
When applying a subscription change with mark_as_paid=true (indicating payment has already been collected), invoices are finalized directly to paid status without syncing to external invoicing providers or consuming existing customer balance. This workflow is designed for scenarios where payment has been collected out-of-band, such as through a checkout flow.
Consider the following plans table:
Plan NameIn 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:
DateManual actionsOrb behavior
07-01-2023Subscription started to Intermediate
  • Orb issues an invoice for $100.
07-04-2023Changed 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-2023Changed 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. plan_changes.png