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

# Subscription incomplete

> Por que uma subscription nasce incomplete, como levá-la a active e o que acontece se a primeira cobrança não fechar.

Quando você cria uma subscription **sem trial** pela API, ela **não nasce ativa**. Ela nasce `incomplete`: o acordo de cobrança recorrente existe, mas o relógio do faturamento só começa a contar depois que a **primeira cobrança** for paga. Esse estado é a porta de entrada de toda assinatura paga — é nele que a primeira fatura é aberta e o pagamento inicial é confirmado.

<Info>
  **`incomplete` é transitório, não um erro.**

  Ele significa "a assinatura foi registrada, mas ainda estou aguardando o primeiro pagamento". Não libere o produto ou o acesso enquanto a subscription estiver `incomplete` — espere `subscription.updated` com `data.object.status: "active"`.
</Info>

## O que a Chargefy cria junto

No mesmo `POST /v1/subscriptions`, três objetos nascem em cadeia. A subscription é só a ponta visível:

```mermaid theme={}
flowchart LR
  S["subscription<br/>status: incomplete"] --> I["invoice<br/>billing_reason: subscription_create<br/>status: open"]
  I --> PI["payment_intent<br/>attempt_number: 1"]
  PI -. confirmação .-> R{{resultado}}
  R -- pago --> A["subscription<br/>status: active"]
  R -- 23h sem pagar --> X["subscription<br/>status: incomplete_expired"]
```

| Objeto           | Estado inicial                                       | Papel                                                                                                                                |
| ---------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `subscription`   | `incomplete`                                         | O acordo recorrente. Guarda `items`, `currency`, `trial_*` e o `default_payment_method`; a cadência vem de `items.data[].recurring`. |
| `invoice`        | `open`                                               | A **primeira fatura** (`billing_reason: "subscription_create"`), já criada com o valor total do primeiro ciclo.                      |
| `payment_intent` | `requires_confirmation` ou `requires_payment_method` | A cobrança que move o dinheiro da primeira fatura. Veja [Payment Intents](/features/payment-intents).                                |

<Note>
  O `payment_intent` nasce em `requires_confirmation` quando você passou `default_payment_method` na criação — nesse caso a Chargefy já enfileira a tentativa de cobrança automaticamente. Sem método padrão, ele nasce em `requires_payment_method` e fica aguardando você definir o meio de pagamento e confirmar.
</Note>

## Ciclo de vida do `incomplete`

A partir de `incomplete`, só existem dois desfechos para o primeiro ciclo: a cobrança fecha e a subscription vira `active`, ou ela expira por inação.

```mermaid theme={}
stateDiagram-v2
  [*] --> incomplete: create sem trial
  [*] --> trialing: create com trial_period_days
  incomplete --> active: primeira cobrança paga
  trialing --> active: trial termina e cobra
  trialing --> past_due: trial termina sem método de pagamento
  trialing --> paused: trial termina sem método + política pause
  trialing --> canceled: trial termina sem método + política cancel
  incomplete --> incomplete_expired: 23h sem pagamento
  active --> past_due: cobrança de renovação falha
  past_due --> unpaid: retries esgotados/política
  past_due --> active: cobrança recuperada
  unpaid --> active: cobrança recuperada
  incomplete_expired --> [*]
```

| Status               | Quando ocorre                                                                                     | É terminal? |
| -------------------- | ------------------------------------------------------------------------------------------------- | ----------- |
| `incomplete`         | Subscription criada sem trial; aguardando a primeira cobrança.                                    | Não         |
| `trialing`           | Subscription criada com `trial_period_days`; a primeira cobrança só ocorre no fim do trial.       | Não         |
| `active`             | A primeira cobrança (ou a do fim do trial) foi paga. Faturamento recorrente em dia.               | Não         |
| `incomplete_expired` | A primeira cobrança não fechou dentro de **23 horas**.                                            | Sim         |
| `past_due`           | Uma cobrança recorrente falhou ou uma invoice de fim de trial foi criada sem método de pagamento. | Não         |
| `unpaid`             | A cobrança foi marcada como não recuperável após política de cobrança/retry.                      | Não         |
| `canceled`           | A subscription foi cancelada.                                                                     | Sim         |
| `paused`             | Trial terminou sem método de pagamento e a política escolhida foi pausar a subscription.          | Não         |

<Warning>
  `incomplete_expired` é **terminal**. Uma subscription que expirou não volta para `incomplete` nem `active` — para o cliente voltar a assinar, crie uma subscription nova.
</Warning>

## Da criação até `active`

<Steps>
  <Step title="Crie a subscription com um método de pagamento padrão">
    Passe `default_payment_method` no create. A subscription nasce `incomplete`, a primeira fatura abre e a Chargefy **enfileira a cobrança automaticamente** no método informado.

    ```bash theme={}
    curl https://api.chargefy.io/v1/subscriptions \
      -H "Authorization: Bearer {{API_KEY}}" \
      -H "Content-Type: application/json" \
      -d '{
        "customer": "cus_456",
        "default_payment_method": "pm_789",
        "items": [{ "price": "price_123" }]
      }'
    ```

    A resposta já volta com `status: "incomplete"` — o pagamento ainda não fechou de forma síncrona.
  </Step>

  <Step title="Aguarde a confirmação da primeira cobrança">
    Cartão costuma resolver na hora; PIX e boleto ficam pendentes até a confirmação assíncrona chegar. Acompanhe o desfecho da cobrança pelos eventos do `payment_intent`, não pela resposta do create.
  </Step>

  <Step title="Reaja ao subscription.updated">
    Quando a primeira fatura é paga, ela vira `paid`, o `payment_intent` vira `succeeded` e a subscription transiciona `incomplete → active`. É nesse ponto que você libera o produto ou o acesso.
  </Step>
</Steps>

### Sem método padrão na criação

Se você criar a subscription **sem** `default_payment_method`, o `payment_intent` da primeira fatura nasce em `requires_payment_method` e nada é cobrado automaticamente. Você precisa definir o meio de pagamento e confirmar a cobrança você mesmo — por exemplo, conduzindo o comprador por um fluxo de [Checkout Session](/features/checkout-sessions) ou orquestrando o [payment intent](/features/payment-intents) diretamente. Enquanto a primeira cobrança não fechar, a subscription permanece `incomplete`.

## Eventos que você recebe

A criação e a transição disparam uma sequência previsível de webhooks. Reaja a eles em vez de depender da resposta síncrona do create.

| Momento                | Evento                     | O que carrega                                                                                 |
| ---------------------- | -------------------------- | --------------------------------------------------------------------------------------------- |
| Subscription criada    | `subscription.created`     | A subscription completa em `data.object`, com `status: "incomplete"`.                         |
| Primeira fatura aberta | `invoice.created`          | A fatura `subscription_create`.                                                               |
| Cobrança iniciada      | `payment.intent.created`   | O intent da primeira cobrança.                                                                |
| Primeira cobrança paga | `payment.intent.succeeded` | A cobrança concluiu.                                                                          |
| Subscription ativada   | `subscription.updated`     | `data.object.status` vem como `active` e `data.previous_attributes.status` traz `incomplete`. |

<Note>
  Na ativação, o `subscription.updated` traz `data.previous_attributes` com `{ "status": "incomplete" }` e o `data.object` com `status: "active"`.
</Note>

## Quando a primeira cobrança não fecha

Se a primeira cobrança **não for paga em até 23 horas**, uma rotina agendada expira a subscription. Nesse passo, em cadeia:

<Steps>
  <Step title="A subscription vira incomplete_expired">
    `incomplete → incomplete_expired`. Esse estado é terminal.
  </Step>

  <Step title="A primeira fatura é anulada">
    A fatura `subscription_create` que estava `open` passa para `void` e dispara `invoice.voided`.
  </Step>

  <Step title="A cobrança pendente é cancelada">
    O `payment_intent` ainda em aberto (`requires_payment_method`, `requires_confirmation`, `pending` ou `processing`) vira `canceled` e dispara `payment.intent.canceled`.
  </Step>
</Steps>

A expiração emite `subscription.updated` com `data.previous_attributes.status = "incomplete"` e `data.object.status = "incomplete_expired"`.

<Warning>
  Uma **falha** na primeira cobrança (cartão recusado, por exemplo) **não** marca a subscription como `past_due`. A primeira fatura continua `open` e a subscription continua `incomplete` — você ainda pode tentar pagar essa fatura — até que a janela de 23 horas a leve a `incomplete_expired`.
</Warning>

## `incomplete` vs `past_due` vs `unpaid`

É comum confundir o estado da **primeira** cobrança com o das **renovações**. A regra é direta:

| Cenário                             | Status resultante    |
| ----------------------------------- | -------------------- |
| Primeira cobrança ainda não fechou  | `incomplete`         |
| Primeira cobrança não fechou em 23h | `incomplete_expired` |
| Cobrança de renovação falhou        | `past_due`           |
| Retry/política de cobrança esgotada | `unpaid`             |

<Note>
  `past_due` aparece em cobranças de **renovação** (`billing_reason: "subscription_cycle"`) ou no fim de trial com `trial_settings.end_behavior.missing_payment_method: "create_invoice"` sem método de pagamento. Ele nunca decorre da primeira cobrança — a primeira só conhece `incomplete`, `active` e `incomplete_expired`.
</Note>

## E o trial?

Uma subscription criada com `trial_period_days` ou `trial_end` **não** passa por `incomplete`. Ela nasce `trialing`, grava `trial_start`/`trial_end` e a primeira cobrança só acontece no fim do trial. Se não houver método de pagamento salvo nesse momento, `trial_settings.end_behavior.missing_payment_method` decide se a Chargefy cria a invoice (`create_invoice`), pausa sem gerar invoice (`pause`) ou cancela a assinatura (`cancel`).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Objeto subscription" icon="cube" href="/api-reference/subscriptions">
    Schema público completo, todos os status e os campos retornados.
  </Card>

  <Card title="Payment Intents" icon="credit-card" href="/features/payment-intents">
    A cobrança que confirma a primeira fatura e leva a subscription a `active`.
  </Card>

  <Card title="Checkout Sessions" icon="cart-shopping" href="/features/checkout-sessions">
    Página hospedada que cria a subscription e confirma a primeira cobrança por você.
  </Card>

  <Card title="Criar subscription (API)" icon="code" href="/api-reference/subscriptions/create">
    Contrato do `POST /v1/subscriptions`.
  </Card>
</CardGroup>