Subscription management
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.
The following timeline illustrates the prorations, assuming that all subscriptions bill on the first of the month and prorate accordingly:
When you make modifications to subscriptions, these changes create new price intervals that can be viewed in the subscription timeline. You can choose to view either “Active prices” (current intervals only) or “All prices” (complete history and future schedule) in the subscription interface. Learn more about price visibility options.
Subscription edits
Subscriptions can be edited independently of their plan to enable functionality like add-on pricing or on-demand discounting.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.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.Modifying adjustments
Adjustments (discounts, minimums, and maximums) on a subscription can be added, removed, and changed in exactly the same way as prices using the subscription price intervals API. This allows you to flexibly update a subscription’s pricing to enable use cases like creating temporary discounts or applying discounts to add-on prices on a subscription.Add-ons and plans
Add-on prices and adjustments, created using the subscription price intervals API on a specific subscription, are not considered part of the plan that subscription is on. These prices and adjustments will not be impacted by plan-specific actions, like plan changes or plan version migrations, and will continue to persist when these actions are taken. In order to make changes to the add-on prices in conjunction with changes to plan prices and adjustment, you’ll need to explicitly modify the add-ons for each subscription. For example, if you add a price on to a subscription called “Premium Storage” that’s only available on your Premium plan, and then the user changes plans to the Basic plan at the end of the billing cycle, you’ll want to use the subscription price intervals API endpoint to schedule the Premium Storage price to end at the end of the billing cycle as well.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, 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 |
| Date | Manual actions | Orb behavior |
|---|---|---|
| 07-01-2023 | Subscription started to Intermediate |
|
| 07-04-2023 | Changed from Intermediate to Advanced |
|
| 07-11-2023 | Changed from Advanced to Beginner |
|
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.Coupons
A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users.How to use coupons
Coupons can be created using the Orb dashboard or programmatically through the API. Once a coupon is created, it can be managed and applied programmatically via the API. To redeem a coupon, use theredemption_code property when creating a subscription or when scheduling a plan change.