> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Lifecycle

> Map subscription statuses into billing, access, retry, and cancellation behavior.

Use the subscription status to decide customer access and operational follow-up.

## Statuses

| Status             | Meaning                                   | Recommended action                                     |
| ------------------ | ----------------------------------------- | ------------------------------------------------------ |
| `incomplete`       | first charge or validation did not finish | wait for recovery or reconcile                         |
| `trialing`         | trial period is active                    | grant trial access until `trial_end`                   |
| `active`           | billing is current                        | keep access active                                     |
| `past_due`         | renewal failed and retry policy applies   | notify the customer and wait for retry or cancellation |
| `cancel_scheduled` | cancellation is scheduled for period end  | keep access until `current_period_end`                 |
| `canceled`         | subscription is finished                  | stop future access and billing                         |

## Renewals

Pagou renews active and trialing subscriptions when the billing period ends. Successful renewals emit `subscription.started` after a trial or `subscription.renewed` for later cycles.

## Failed payments

`failure_policy` controls what happens after a failed renewal:

* `retry_then_cancel`: move through retry handling before cancellation.
* `immediate_cancel`: cancel when the renewal cannot be collected.

Use `retry_offsets_days` only when you need explicit retry spacing.

## Cancellation

`POST /v2/subscriptions/{id}/cancel` schedules cancellation at the end of the current period. The subscription becomes `cancel_scheduled` immediately and later moves to `canceled`.

## Read next

* [Subscription Webhooks](/subscriptions/webhooks)
* [API: Update a Subscription](/api-reference/subscriptions/update)
* [API: Cancel a Subscription](/api-reference/subscriptions/cancel)