# How subscriptions work

> An explanation of the subscription lifecycle from plan creation to recurring charges, renewal changes, and cancellation.

Paystack subscriptions are built on a simple sequence: **plan → subscription → invoice cycle → status change or cancellation**.

A **plan** defines the recurring amount and interval. It is the pricing template for the subscription. A plan can be created in the Dashboard or through the API with a name, interval, and amount. It can also include an `invoice_limit` to stop charging after a fixed number of cycles.

A **subscription** is created when a customer is attached to a plan. This can happen in two ways. The first is by adding a `plan_code` to a transaction initialization request, which charges the customer and subscribes them in one flow. The second is by calling the create subscription endpoint for a customer who already has a reusable authorization on your integration.

Once a subscription exists, Paystack manages the charge cycle. Three days before the next payment date, an `invoice.create` event signals that a charge attempt is approaching. On the payment date, either `charge.success` confirms a successful debit or `invoice.payment_failed` reports that the attempt failed. Afterward, `invoice.update` reflects the final invoice state for that cycle.

Subscription status shows where the customer is in the lifecycle:

- `active`: the subscription is live and due to be charged on the next payment date.
- `non-renewing`: the subscription remains active for the current cycle but will not renew.
- `attention`: the subscription is active but the latest charge attempt failed.
- `completed`: the subscription reached the end of its billing life.
- `cancelled`: the subscription has been cancelled and is no longer chargeable.

Cancellation is also event-driven. `subscription.not_renew` indicates that renewal has been turned off for the next cycle. `subscription.disable` marks the point where the subscription is actually disabled. When all billing cycles are exhausted, the final disable event is sent with a completed state.

This event model makes webhooks central to subscription operations because the billing timeline continues even when the customer is no longer on your site.
