# 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 price's recurring 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`) | A renewal could not be attempted; 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 `true` exactly when `autoBillingEnabled` is `false` with `autoBillingDisabledReason: latest_invoice_retrying`, the state a subscription is in while a failed renewal payment is retried. It reads only those two fields and says nothing about whether another attempt is scheduled. It returns to `false` when billing is restored or the subscription is cancelled.

### Why a subscription was cancelled

A cancelled subscription says why in `cancellationReason`:

| `cancellationReason`   | Meaning                                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `requested`            | You cancelled it, immediately or at a period end you booked                                                                           |
| `payment_failed`       | A renewal payment failed and could not be recovered                                                                                   |
| `chargeback`           | One of its payments was [charged back](https://docs.odus.com/docs/guides/payments/chargebacks.md)                                     |
| `customer_blacklisted` | You added the customer's email to the [Blacklist](https://docs.odus.com/docs/guides/customers/customer-restrictions.md#the-blacklist) |

It is `null` while the subscription is `active`, and on subscriptions cancelled before the field was introduced. A booked cancellation does not set it until the subscription is actually cancelled.

### 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](https://docs.odus.com/docs/guides/subscriptions/canceling-and-resuming.md) 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](#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**, what happens next depends on the decline:

* If the payment can be retried, ODUS starts a payment retry sequence. The subscription's `autoBillingEnabled` is set to `false` with reason `latest_invoice_retrying`. If a retry succeeds, `autoBillingEnabled` is restored and normal billing resumes. If the retries end without a successful payment, ODUS voids the invoice and cancels the subscription.
* If the payment cannot be retried, for example after a hard decline, ODUS cancels the subscription immediately.

Either cancellation sends a `subscription.cancelled` event.

Billing can stop without a cancellation

Sometimes a renewal cannot be attempted at all, because of an error before any charge is made. ODUS then sets `autoBillingEnabled` to `false` with reason `recurring_payment_errored`, and the subscription stays `active` without renewing. No charge was attempted, so nothing was declined. Cancel the subscription, or [reactivate it](https://docs.odus.com/docs/guides/subscriptions/canceling-and-resuming.md#reactivating-a-subscription-whose-billing-stopped) to restart billing.

To find these subscriptions, filter `GET /v2/subscriptions` with `autoBillingDisabledReason[eq]=recurring_payment_errored`.

## 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, so a subscription gains one every billing cycle.

A v2 subscription object does not list its invoices. Read them from [`GET /v2/invoices`](https://docs.odus.com/docs/api/core/v2/invoice-controller-find-all-paginated) filtered by the subscription:

```
GET /v2/invoices?subscription[eq]=sub_2Q9fNQAs77Fhue9itgVFbUzq8NV
```

The list is paged, so follow `pagination.nextCursor` until `hasNextPage` is `false`. Your key needs `invoice:read`.

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](https://docs.odus.com/docs/guides/payments/chargebacks.md) for how to record one.

Blacklisting cancels the subscription

If you add the customer's email to the Blacklist, ODUS cancels **immediately** every active subscription of every customer with that email. As with a chargeback, invoice statuses are not changed, and no new charge is attempted, because the Blacklist refuses it. See [The Blacklist](https://docs.odus.com/docs/guides/customers/customer-restrictions.md#the-blacklist).

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 /v2/invoices/{id}`](https://docs.odus.com/docs/api/core/v2/invoice-controller-find-one)) 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](https://docs.odus.com/docs/guides/subscriptions/payment-bundling.md) 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](https://docs.odus.com/docs/guides/subscriptions/updating-plans.md) — how to change a subscription's pricing plan, including proration
* [Payment Bundling](https://docs.odus.com/docs/guides/subscriptions/payment-bundling.md) — how multiple subscriptions can be charged in a single payment
* [Cancelling and Resuming](https://docs.odus.com/docs/guides/subscriptions/canceling-and-resuming.md) — how to cancel a subscription immediately, at period end, or after one more renewal, and how to reverse a scheduled cancellation