> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Run the Recurring Revenue Lifecycle
> Understand how a recurring catalog item becomes an ongoing customer relationship.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
A subscription is Ruba’s record of an ongoing agreement between one customer and one recurring catalog item. Checkout normally creates it, the renewal engine advances it, and its state determines whether attached benefits remain available.
## The subscription lifecycle
After the first checkout succeeds, Ruba records both the initial [order](/features/orders) and the subscription that will control future billing periods.
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.
A successful renewal leaves the subscription active. A failed charge moves it to `past_due` and begins the [recovery schedule](/features/subscriptions/failed-payments).
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](/api-reference/subscriptions/create). 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:
| Decision | Available behavior |
| -------------- | --------------------------------------------------------------------------- |
| Cadence | Daily, weekly, monthly, or yearly. |
| Interval count | Multiply the cadence, such as every 2 months. |
| Price model | Fixed amount, pay what you want, or free. |
| Currency | The currency selected during checkout remains attached to the subscription. |
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](/features/subscriptions/manage#change-the-plan).
## 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.
Free subscriptions and subscriptions already set to end at the current period are excluded. You can disable these messages under **Settings → Customer notifications**.
## Cancellation
Ending renewal and ending access are separate decisions.
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.
Revoke immediately to move the subscription to `canceled` and remove its benefits at once. This action cannot be reversed.
Customers can perform the actions you permit from the [Customer Portal](/features/customer-portal/introduction). Your team can operate the full lifecycle from the dashboard or API.
## Decisions and edge cases
The catalog item defines what is sold: its copy, price, cadence, and benefits. A subscription records one customer’s continuing relationship with that item.
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.
Checkout collects it immediately unless the item includes a trial. With a trial, the first charge is attempted when that trial ends.
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.
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](/features/subscriptions/failed-payments#benefit-revocation-grace-period).
## Continue the build
Change plans, quantities, discounts, trial dates, renewal dates, and cancellation state.
Decide when a plan change applies and when its difference is charged or credited.
Follow retry timing, customer recovery, and benefit revocation.
Read and operate subscription records programmatically.