Payments
How subscriptions work
In a nutshell
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.