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	cancelAtPeriodEnd	autoBillingEnabled	Meaning
Billing normally	active	false	true	The subscription will be charged at the next renewal date
Scheduled to cancel	active	true	true	The subscription will not renew; it cancels at currentPeriodEnd
Payment retrying	active	false	false (latest_invoice_retrying)	The latest invoice payment failed and a retry is in progress
Billing stopped	active	false	false (recurring_payment_errored)	Retries were exhausted; no further automatic charges will occur
Cancelled	cancelled	—	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

When a subscription is cancelled with cancelImmediately: false, it enters a pending cancellation state: status remains active and cancelAtPeriodEnd is set to true. The customer retains access until currentPeriodEnd. After that date, Odus cancels the subscription automatically without charging.

This 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

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
paid	The associated payment succeeded
voided	The invoice was cancelled without being charged (for example, after a failed plan-update payment)

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 succeeds, the invoice becomes paid and the subscription advances to the March period. If it 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 or at period end, and how to reverse a scheduled cancellation