Subscription management
Creating subscriptions
A subscription represents a Customer’s recurring purchase of a plan.
A subscription’s current status is a function of its start and end date.
How to create a subscription
You can create a subscription either from the Orb UI or via the subscription creation API endpoint.When to choose which path?
| If you need… | Choose… |
|---|---|
| Standardized experiences for many customers | Plan Template |
| Custom rates, terms, or structures for a single customer | Plant Template with overrides |
Subscription lifecycle
A subscription’s term is the length of time which determines its renewal cadence, determined by looking at the maximum cadence among all its component prices. A subscription’s billing period is the length of time that determines how often invoices are generated, aligned to a bill cycle day. It can be determined by looking at the minimum cadence among all the component prices.| Component prices | Term | Billing period |
|---|---|---|
| 2 Monthly usage charges | Monthly | Monthly |
| 2 Monthly usage charges, Annual platform fee | Annual | Monthly |
| Monthly charge for storage, Quarterly charge for services, Annual platform fee | Annual | Monthly |
| Quarterly charge for services, Annual fee | Annual | Quarterly |
| Status | Description |
|---|---|
upcoming | The subscription’s start_date is in the future. Sending usage data for the corresponding customer will not be associated with any charges since there is no active subscription. |
active | The subscription is currently active, and may accrue charges as usage events are ingested. |
ended | The subscription’s end_date is in the past, likely as a result of a cancellation. |
Billing cycle alignment
By default, monthly subscriptions that are created will be billed on the first of each month, and any in-advance charges (e.g. a platform access fee) will be appropriately pro-rated on the first invoice. This behavior is often desirable because it provides a consistent reference point for internal processes, such as accounting. Orb also allows you to align the billing cycles with the date that the subscription was created. If a subscription was created on the 14th of November and involved a monthly price, this behavior would enable you to consistently invoice the customer on the 14th of each month. Orb recommends that you use this behavior if you’d like to avoid pro-rating any in-advance fees on the first invoice. If the anchored day is not present in the current month (e.g. billing in February for a subscription that started on Jan 31), then the last day of the month is used. If neither of those options are sufficient, Orb supports fully custom billing cycle alignment by specifying a date on which billing cycles are anchored. For example, a quarterly subscription anchored on March 16, 2024 with a start date of October 10, 2023 and an end date of March 16, 2024 would have the following billing periods:- October 10, 2023 - December 16, 2023
- December 16, 2023 - March 16, 2024
Cancellation behaviors
A subscription can be cancelled either effective immediately or at the end of its subscription term. If a subscription is cancelled end of term, it will continue to invoice every billing period until the term is exhausted. Orb also allows canceling a subscription effective a past date. The following examples illustrate how this is handled, where the cancellation action occurs on the “action date” but therequested_date (via the cancel subscription endpoint) is the effective date. Note that backdated cancellations are allowed only if there are no paid invoices between the action date and the requested date. In these examples, assume that the subscription bills $50 monthly up front, and has a usage based fee.
| Subscription start date | Cancellation action date | Cancellation effective date | Behavior |
|---|---|---|---|
| 01-01-2022 | 01-15-2022 | 01-13-2022 | Consistent with prorations for in-advance fees, Orb will generate a balance refund for the unused time for the month of January, and an in-arrears invoice capturing any usage from 01-01 to 01-13. |
| 01-01-2022 | 01-15-2022 | 01-01-2022 | Orb will void the invoice issued on 01-01, and generate no further invoices. |
| 01-01-2022 | 02-15-2022 | 02-01-2022 | Orb will void the invoice issued on 02-01 which includes the upfront charge for February, and issue a new invoice for 02-01 capturing the usage for the month of January. |
When backdating the cancellation of a subscription that includes prepaid credits, the credit consumption for the period between the cancellation action date and the cancellation effective date will be undone.
Subscription timeline
Orb’s subscription timeline allows you to visualize prices on a subscription over time along with the subscription’s invoices, allowing you to easily understand the history of the subscription and preview any upcoming changes.
Understanding price visibility: Active vs. All prices
When viewing subscription details, you have two options for price visibility that control which price intervals are displayed:- Active prices: Shows only the price intervals that are currently active (effective right now). This provides a snapshot of what prices are currently being charged on the subscription.
-
All prices: Shows the complete history and future schedule of price intervals on the subscription, including:
- Historical prices: Previous price intervals that have ended
- Current prices: Price intervals that are currently active
- Future prices: Scheduled price intervals that will start in the future (e.g., planned price changes or add-ons)
The “All prices” view includes price intervals created through subscription edits, plan changes, and any scheduled pricing modifications, giving you complete transparency into the subscription’s pricing timeline.
Trials
A subscription’s trial is determined by its trial configuration on the plan level. However, even in the case that a Subscription’s plan is changed (see below), a subscription is always eligible for at most one trial and will never undergo a second trial, even if its new plan normally has a trial phase.Subscription price overrides
When creating a customer’s subscription to a plan where the existing plan terms need to be adjusted (e.g. because a specific amount has been negotiated differently), Orb provides the ability to override plan configuration. When creating a subscription, you may modify (override) or remove prices and adjustments from the plan, or add net new prices that did not exist on the plan. This allows the creation of a wide variety of custom plans using a small number of template plans, without having to construct the new plans from scratch. It also makes it easy to create add-ons to existing plans and subscriptions. Overrides to prices on a subscription will be applied by replacing the plan prices with newly created prices at the start of the subscription. Orb will replace the minimal amount of prices when creating the subscription, so any prices that have not been overridden will retain the same ids as the plan prices.Some existing Orb accounts may still be on Orb’s legacy overrides behavior, which dynamically creates an entirely new plan to represent overrides rather than replacing the minimal set of prices and adjustments on the existing plan. If you’re unsure which behavior your Orb account is using for overrides, please reach out to support.