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. |
Day 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 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.
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. |
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.
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, dynamically creating a new plan. This provides the benefit that the new plan does not need to be constructed from scratch, and can inherit the defaults from a base configuration.
To provide the ability to trace the original template from which one-off deals arise, Orb also tracks plan lineage, where each plan may be associated with a base plan. Information about the source plan can be used to understand how plans evolve over time, as well as perform orchestration actions per cohort.