# Ciclo de vida da assinatura

URL: https://staging.pagpolar.com/docs/guias/conceitos/ciclo-de-vida-da-assinatura

> Entenda por que a assinatura nasce DRAFT, quando fica ACTIVE, como renova e como termina.

## O problema: a confirmação chega depois

Quando você chama [`POST /plans/offer/{id}/subscribe`](/docs/referencia/assinaturas/create-subscription), a resposta `201` chega **antes** de o gateway criar a assinatura. Por isso a resposta sempre traz `status: DRAFT`, mesmo quando tudo vai dar certo.

O resultado chega depois, pelos webhooks ou por [`GET /subscriptions/{id}`](/docs/referencia/assinaturas/get-subscription).

Existem dois tipos de assinatura, com caminhos diferentes:

| Tipo              | Como nasce                            | Quem cobra a cada ciclo                        |
| ----------------- | ------------------------------------- | ---------------------------------------------- |
| Cartão de crédito | Pela API ou pelo checkout da PagPolar | O gateway                                      |
| PIX ou boleto     | Só pelo checkout da PagPolar          | A PagPolar gera uma cobrança nova a cada ciclo |

Pela API, a assinatura é sempre no cartão. As assinaturas em PIX ou boleto aparecem nos webhooks e nas consultas porque o webhook da sua credencial também [recebe as vendas do checkout](/docs/webhooks/formato-do-evento#source).

## Assinatura no cartão

O diagrama mostra os status de uma assinatura no cartão.

```mermaid
stateDiagram-v2
  [*] --> DRAFT: POST /plans/offer/ID/subscribe
  DRAFT --> FAILED: gateway recusa a criação
  DRAFT --> ACTIVE: gateway informa a cobrança paga
  ACTIVE --> PROCESSING: gateway informa cobrança pendente
  PROCESSING --> ACTIVE: gateway informa a cobrança paga
  ACTIVE --> CANCELING: DELETE /subscriptions/ID
  CANCELING --> CANCELED: gateway confirma o cancelamento
  ACTIVE --> CANCELED: gateway informa cancelamento ou recusa
  ACTIVE --> EXPIRED: gateway informa assinatura expirada
  ACTIVE --> FAILED: gateway informa falha
```

| Status       | Significado                                                                                  | Evento                                                                                                                                                                                                                                                 | O que fazer                                                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `DRAFT`      | Assinatura registrada. O gateway ainda não confirmou.                                        | [`SUBSCRIPTION_CREATED`](/docs/webhooks/eventos/subscription-created) e depois [`SUBSCRIPTION_CONFIRMED`](/docs/webhooks/eventos/subscription-confirmed)                                                                                               | Registre. Não libere o acesso.                                                                                                         |
| `ACTIVE`     | A cobrança do ciclo foi paga.                                                                | Primeiro ciclo: nenhum evento de assinatura próprio; confira `status` em [`GET /subscriptions/{id}`](/docs/referencia/assinaturas/get-subscription). A partir do segundo ciclo: [`SUBSCRIPTION_RENEWED`](/docs/webhooks/eventos/subscription-renewed). | Libere ou mantenha o acesso.                                                                                                           |
| `PROCESSING` | O gateway informou uma cobrança pendente.                                                    | Nenhum evento próprio                                                                                                                                                                                                                                  | Consulte a assinatura se precisar do detalhe.                                                                                          |
| `CANCELING`  | Você pediu o cancelamento e o gateway ainda não confirmou.                                   | Nenhum evento                                                                                                                                                                                                                                          | Espere `SUBSCRIPTION_CANCELED`.                                                                                                        |
| `CANCELED`   | O cancelamento foi efetivado, a pedido seu ou por aviso do gateway (cancelamento ou recusa). | [`SUBSCRIPTION_CANCELED`](/docs/webhooks/eventos/subscription-canceled)                                                                                                                                                                                | Revogue o acesso. Se precisar da data, confira `end_at` em [`GET /subscriptions/{id}`](/docs/referencia/assinaturas/get-subscription). |
| `FAILED`     | O gateway recusou a criação ou informou falha.                                               | [`SUBSCRIPTION_FAILED`](/docs/webhooks/eventos/subscription-failed) na criação                                                                                                                                                                         | Não libere o acesso.                                                                                                                   |
| `EXPIRED`    | O gateway informou que a assinatura expirou.                                                 | Nenhum evento próprio no cartão                                                                                                                                                                                                                        | Revogue o acesso.                                                                                                                      |

> **SUBSCRIPTION_CONFIRMED não ativa a assinatura**
>
> Depois de `SUBSCRIPTION_CONFIRMED`, o status **continua `DRAFT`**. Ele só vira `ACTIVE` quando o gateway informa a cobrança paga.

O status segue sempre o último aviso do gateway. Por isso a assinatura pode sair de qualquer status para outro, conforme o gateway informa.

`DELETE /subscriptions/{id}` só muda o status de uma assinatura no cartão quando ela está `ACTIVE`. Em outro status, a resposta é `200` e nada muda.

## Assinatura em PIX ou boleto

O diagrama mostra os status de uma assinatura em PIX ou boleto.

```mermaid
stateDiagram-v2
  [*] --> PENDING_PAYMENT: venda no checkout
  PENDING_PAYMENT --> ACTIVE: primeira cobrança paga
  ACTIVE --> PENDING_RENEWAL: chegou a data da próxima cobrança
  PENDING_RENEWAL --> ACTIVE: cobrança de renovação paga
  PENDING_RENEWAL --> EXPIRED: prazo de carência acabou sem pagamento
  PENDING_PAYMENT --> CANCELED: pedido de cancelamento
  ACTIVE --> CANCELED: pedido de cancelamento
  PENDING_RENEWAL --> CANCELED: pedido de cancelamento
```

| Status            | Significado                                          | Evento                                                                                                                                                                                             | O que fazer                  |
| ----------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `PENDING_PAYMENT` | Espera o pagamento da primeira cobrança.             | [`SUBSCRIPTION_CREATED`](/docs/webhooks/eventos/subscription-created)                                                                                                                              | Não libere o acesso.         |
| `ACTIVE`          | O ciclo está pago.                                   | [`TRANSACTION_PAID`](/docs/webhooks/eventos/transaction-paid) da cobrança do ciclo                                                                                                                 | Libere ou mantenha o acesso. |
| `PENDING_RENEWAL` | Chegou a data da renovação e ela ainda não foi paga. | [`TRANSACTION_PENDING`](/docs/webhooks/eventos/transaction-pending) quando a nova cobrança é gerada e [`SUBSCRIPTION_DELAYED`](/docs/webhooks/eventos/subscription-delayed) enquanto está atrasada | Lembre o cliente de pagar.   |
| `EXPIRED`         | O prazo de carência acabou sem pagamento.            | [`SUBSCRIPTION_EXPIRED`](/docs/webhooks/eventos/subscription-expired)                                                                                                                              | Revogue o acesso.            |
| `CANCELED`        | Cancelada na hora do pedido.                         | [`SUBSCRIPTION_CANCELED`](/docs/webhooks/eventos/subscription-canceled)                                                                                                                            | Revogue o acesso.            |

Diferenças em relação ao cartão:

* A renovação paga chega como `TRANSACTION_PAID`. **Não** existe `SUBSCRIPTION_RENEWED` para PIX ou boleto.
* O cancelamento vale na hora, sem passar por `CANCELING`.
* A PagPolar confere atrasos e expirações uma vez por dia.

## Reembolso, estorno e chargeback cancelam a assinatura

Pedidos de reembolso, estornos e chargebacks de vendas da assinatura também pedem o cancelamento dela. Veja em quais casos em [Reembolso e chargeback também cancelam](/docs/guias/jornadas/cancelar-assinatura#reembolso-e-chargeback).

## Guias relacionados

- [Catálogo de eventos](/docs/webhooks/eventos) — Todos os eventos de assinatura.
- [Ciclo de vida da venda](/docs/guias/conceitos/ciclo-de-vida-da-venda) — Cada cobrança da assinatura é uma venda com status próprio.
