Creating subscriptions
A subscription represents a Customer’s recurring purchase of a plan.
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 |
A subscription’s current status is a function of its start and end date.
| 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
Note that the first period will be pro-rated because the start date of the subscription is not aligned with the anchor date (the full billing period would be September 16, 2023 - December 16, 2023).
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 the requested_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.
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.
Coupons
Coupons can be applied when creating a subscription to easily give a discount to a customer in a repeatable way, which is useful for modeling situations like employee or promotional discounts. When a coupon is provided, Orb will automatically create a amount or percentage discount adjustment as specified in the coupon configuration and apply it to all of the prices on the subscription at the time of creation. Please note that coupons do not scope in new price additions to a subscription automatically — if a new price is added to the subscription with a subscription edit or plan version migration, the discount created with the coupon will not apply to it automatically.
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.
Note: 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.