The subscription lifecycle
1
Checkout establishes the relationship
After the first checkout succeeds, Ruba records both the initial order and the subscription that will control future billing periods.
2
The period advances
When
current_period_end is reached, Ruba opens the next period, prepares another order with the applicable tax and discount, and charges the saved payment method.3
Payment determines the next state
A successful renewal leaves the subscription active. A failed charge moves it to
past_due and begins the recovery schedule.4
Access follows subscription state
Benefits stay granted while the relationship is active or trialing. Cancellation, revocation, or an unrecovered payment can remove that access according to the configured grace period.
Bringing subscriptions into existence
Paid recurring items always begin through checkout because Ruba must collect and validate a payment method. Free recurring items have a second route: create the subscription directly for an existing customer through the Create Subscription operation. That route does not create an initial order, send a confirmation email, or collect money.Recurring pricing
The catalog item supplies the commercial rules that the subscription locks in:
Cadence and price model cannot be replaced on the same catalog item after creation. Create another item when those structural rules need to differ, then move eligible subscribers through the subscription update flow.
Renewal reminders
Ruba sends an advance reminder seven days before a renewal when the billing cycle is at least six months. The threshold includes:- yearly plans;
- monthly plans with an interval count of at least 6;
- weekly plans with an interval count of at least 25; and
- daily plans with an interval count of at least 180.
Cancellation
Ending renewal and ending access are separate decisions.Stop after the paid period
Cancel at period end to keep the subscription and its benefits active through
current_period_end. This pending cancellation can be reversed before that timestamp.Remove access now
Revoke immediately to move the subscription to
canceled and remove its benefits at once. This action cannot be reversed.Decisions and edge cases
How is a subscription different from a catalog item?
How is a subscription different from a catalog item?
The catalog item defines what is sold: its copy, price, cadence, and benefits. A subscription records one customer’s continuing relationship with that item.
Can an organization allow several subscriptions per customer?
Can an organization allow several subscriptions per customer?
The default is one active subscription for each customer within an organization. If your model requires parallel subscriptions, enable Allow multiple subscriptions under the organization’s subscription settings.
When does the first charge happen?
When does the first charge happen?
Checkout collects it immediately unless the item includes a trial. With a trial, the first charge is attempted when that trial ends.
Does editing a catalog price change current subscriptions?
Does editing a catalog price change current subscriptions?
No. Current subscriptions retain the amount captured when they began. A catalog price edit affects later purchases. Move an existing customer to another price by changing the subscription’s product or allowing a portal plan change.
When are benefits removed?
When are benefits removed?
A period-end cancellation preserves benefits through the paid term. Immediate revocation removes them now. Exhausted payment recovery removes them when the subscription becomes unpaid, subject to the organization’s configured benefit grace period.
Continue the build
Operate subscriptions
Change plans, quantities, discounts, trial dates, renewal dates, and cancellation state.
Choose proration
Decide when a plan change applies and when its difference is charged or credited.
Recover failed renewals
Follow retry timing, customer recovery, and benefit revocation.
Use the API
Read and operate subscription records programmatically.