Subscription Lifecycle

A subscription in Odus is a recurring billing agreement between a merchant and a customer for a specific product and price. Once created, Odus automatically charges the customer at each renewal date according to the pricing plan's billing schedule — no further action is required from your backend.

This page explains how subscriptions work conceptually: what states they move through, how billing cycles operate, and how subscriptions relate to invoices and payments.

What a Subscription Represents

A subscription ties together three things:

• A customer — who is being billed
• A price — what they are being billed for, and how often
• Billing settings — which payment method type, gateway profile, and capture configuration to use for recurring charges

When a subscription is created, Odus records a startDate, an initial currentPeriodStart and currentPeriodEnd, and a currentCycle counter (starting at 1). These values advance automatically with each successful billing cycle.

Subscription Statuses

The status field on a subscription has two values: active and cancelled. However, what a subscription is doing at any point in time depends on several fields together.

State	status	cancelAtCycle	cancelAtPeriodEnd	autoBillingEnabled	Meaning
Billing normally	active	null	false	true	The subscription will be charged at the next renewal date
Scheduled to cancel	active	currentCycle	true	true	The subscription will not renew; it cancels at currentPeriodEnd
Cancelling after renewal	active	a later cycle	false	true	One more renewal will be charged, then the subscription cancels
Payment retrying	active	either	either	false (latest_invoice_retrying)	The latest invoice payment failed and a retry is in progress
Billing stopped	active	either	either	false (recurring_payment_errored)	Retries were exhausted; no further automatic charges will occur
Cancelled	cancelled	null	false	false (subscription_cancelled)	The subscription has ended

The autoBillingDisabledReason field specifies why autoBillingEnabled was set to false, which is important for understanding whether the situation is temporary (a retry is pending) or permanent (billing has stopped).

The isRecovering flag is set to true after a subscription that experienced a payment failure has since had that payment succeed. It is informational and does not block future billing.

Pending Cancellation

A pending cancellation is recorded as cancelAtCycle — the cycle at whose end the subscription will be cancelled. status remains active throughout, and cancelAtPeriodEnd is simply whether that cycle is the one the subscription is in right now (cancelAtCycle === currentCycle).

• Cancelling with cancelAt: "end_of_current_cycle" books the current cycle, so cancelAtPeriodEnd is true immediately. The customer retains access until currentPeriodEnd, and Odus cancels after that date without charging.
• Cancelling with cancelAt: "end_of_next_cycle" books the next one, so cancelAtPeriodEnd stays false and the upcoming renewal is charged as normal. It flips to true by itself once that renewal advances the cycle.

Because the booking is a cycle number rather than a date, it survives the period boundary moving — for instance through the retry delays described below.

Either state can be reversed — see the Cancelling and Resuming guide for details.

The Billing Cycle

Odus evaluates subscriptions for renewal continuously. When a subscription's currentPeriodEnd is reached, Odus creates a recurring invoice and attempts to charge the customer's default payment method using the billing settings recorded on the subscription.

When a renewal succeeds, Odus advances the subscription to the next period:

• currentPeriodStart and currentPeriodEnd move forward by one billing interval
• currentCycle increments by one
• The invoice moves to paid once its payment is captured (see Subscriptions, Invoices, and Payments below)

Period advancement depends on the payment being authorized, not on the invoice reaching paid. With delayed or manual capture, the subscription still advances at authorization while its invoice remains open until the funds are captured. The same period is never authorized twice.

When a renewal fails, Odus starts a payment retry sequence. The subscription's autoBillingEnabled is set to false with reason latest_invoice_retrying. If the retry eventually succeeds, autoBillingEnabled is restored and normal billing resumes. If all retry attempts are exhausted, autoBillingEnabled remains false with reason recurring_payment_errored, and no further automatic charges occur.

warning

When billing stops due to exhausted retries, the subscription is not automatically cancelled — it stays active but with autoBillingEnabled: false. The customer effectively has a subscription that no longer renews. You may want to cancel it explicitly or prompt the customer to update their payment method.

Subscriptions, Invoices, and Payments

A subscription does not charge the customer directly. Instead, Odus creates an invoice for each billing event, and a payment settles the invoice.

Subscription
  └── Invoice (type: setup)       ← created when the subscription is set up
  └── Invoice (type: recurring)   ← created at each renewal
        └── Payment               ← the actual charge attempt

There are two invoice types:

• setup — created when the subscription is first activated. The setupInvoice field on a subscription always points to this invoice.
• recurring — created at each renewal. These accumulate in the subscription's invoices array over time.

An invoice has three possible statuses:

Invoice status	Meaning
open	The invoice has been created but not yet paid or voided. An authorized-but-not-yet-captured invoice stays open
paid	The associated payment was captured (the funds were collected)
voided	The invoice was cancelled without being charged (for example, after a failed plan-update payment)

paid and voided are terminal: an invoice moves from open to exactly one of them and does not change again. A chargeback or refund after an invoice is paid is recorded on the payment, not by changing the invoice status.

Chargebacks cancel the subscription

If a subscription payment is charged back — whether the setup payment or a recurring renewal — Odus cancels the subscription immediately. The subscription moves to cancelled and autoBillingEnabled becomes false. Consistent with the rule above, the chargeback does not change any invoice status: settled invoices stay paid, and a still-open invoice is left to its own payment lifecycle rather than being voided. See the Chargebacks guide for how to record one.

note

An invoice becomes paid when its payment is captured, not when it is authorized. For an automatically captured payment, authorization and capture happen together, so the invoice becomes paid immediately. For a delayed or manual capture, the invoice stays open between authorization and capture, then becomes paid once the funds are collected.

Each invoice carries a subscription field pointing back to the subscription that generated it. The full invoice object (from GET /invoices/:id) includes a payment field with the associated payment details, including status and transaction history.

Example

A customer subscribes to a monthly plan on January 1. Odus creates a setup invoice and charges it immediately. On February 1, Odus creates a recurring invoice and charges the default payment method. If the February charge is captured, the invoice becomes paid and the subscription advances to the March period. If capture is deferred (delayed or manual capture), the subscription still advances to March at authorization while the February invoice stays open until the funds are captured. If the charge fails, the invoice stays open while retries are in progress.

When payment bundling is enabled, multiple subscriptions can share a single payment. In that case, each subscription still has its own invoice, but all invoices in the bundle are attached to one payment object.

Related Guides

• Updating Plans — how to change a subscription's pricing plan, including proration
• Payment Bundling — how multiple subscriptions can be charged in a single payment
• Cancelling and Resuming — how to cancel a subscription immediately, at period end, or after one more renewal, and how to reverse a scheduled cancellation