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

# Assinaturas: visão geral

> Como a Z2Pay modela cobrança recorrente — Plano, Preço, Assinatura e Fatura — e por onde começar a integrar.

Para cobrar de forma recorrente na Z2Pay, você cria uma **assinatura** — ela gera uma **fatura** a
cada ciclo, e cada fatura cobrada vira uma **transação** (visível no dashboard com origem
`billing`).

<Note>
  Os exemplos desta seção usam a base de sandbox `https://api.sandbox.z2pay.com/v1` e o header
  `x-api-key` com a sua chave de sandbox. Veja
  [Autenticação](/pt-BR/autenticacao) e [Ambientes](/pt-BR/ambientes).
</Note>

## O modelo: Plano → Preço → Assinatura → Fatura

A recorrência é construída a partir de quatro recursos encadeados. Entender essa cadeia é o
primeiro passo para integrar.

<CardGroup cols={2}>
  <Card title="Plano (Plan)" icon="layout-template" href="/pt-BR/subscriptions/plans">
    O catálogo da oferta recorrente: nome, código e os **itens** que a compõem. Nasce publicado
    (`active`), pode ser pausado (`inactive`, pelo painel) e arquivado
    (`archived`).
  </Card>

  <Card title="Preço (Price)" icon="tags" href="/pt-BR/subscriptions/plans">
    Uma **versão de preço** de um item do plano: define `amount` (em centavos) e a
    `recurrence` (a cada quanto cobra). Versionado — criar um novo Preço
    desativa o anterior da mesma moeda/recorrência.
  </Card>

  <Card title="Assinatura (Subscription)" icon="repeat" href="/pt-BR/subscriptions">
    Vincula um **cliente** a um plano (ou a itens avulsos). É o contrato vivo: tem status,
    método de pagamento padrão, data da próxima fatura e ciclos.
  </Card>

  <Card title="Fatura (Invoice)" icon="receipt" href="/pt-BR/subscriptions/invoices">
    O documento de cobrança de **um ciclo**. Nasce de uma assinatura, é cobrada e
    transiciona entre `open`, `paid`, `past_due`, etc.
  </Card>
</CardGroup>

```mermaid theme={null}
flowchart LR
  Plan["Plano<br/>(active)"] --> Price["Preço<br/>(amount, recurrence)"]
  Price --> Sub["Assinatura<br/>(cliente + plano)"]
  Customer["Cliente"] --> Sub
  Sub -->|"a cada ciclo"| Invoice["Fatura"]
  Invoice -->|"cobrança"| Charge["Transação"]
```

<Info>
  Você **não precisa** criar um Plano para ter uma assinatura. É possível criar uma assinatura
  com **itens avulsos** (inline), informando `description` e `unitAmount` diretamente — nesse caso
  `recurrence` e `currency` passam a ser obrigatórios no corpo da assinatura. O caminho via Plano
  é o recomendado quando você vende a mesma oferta para muitos clientes.
</Info>

## Como os ciclos funcionam

Depois que a assinatura existe, o nosso agendador cuida do resto. A cada ciclo ele gera a próxima
fatura, dispara a cobrança e atualiza o status da assinatura conforme o resultado.

<Steps>
  <Step title="Criação">
    Você cria a assinatura (`POST /subscriptions`). Sem trial nem adesão: com
    `defaultPaymentMethodRef` ela nasce `active`; sem forma de pagamento, nasce `incomplete`.
    Trial e adesão têm estados iniciais próprios — veja
    [a tabela completa](/pt-BR/subscriptions/create).
  </Step>

  <Step title="Geração da fatura">
    Por padrão (`invoiceGenerationMode=just_in_time`) o agendador gera **uma fatura por ciclo**.
    Em `upfront`, todas as `maxCycles` faturas são emitidas já na criação (cada uma com vencimento
    próprio).
  </Step>

  <Step title="Cobrança">
    Cobramos a forma de pagamento padrão da assinatura, e cada cobrança vira uma **transação**.
    Sem forma de pagamento definida, a fatura é emitida e fica aguardando — use o link público dela
    para o cliente pagar.
  </Step>

  <Step title="Próximo ciclo">
    Paga a fatura, o agendador avança a assinatura para o próximo ciclo e repete — até atingir
    `maxCycles` (se definido) ou até cancelamento.
  </Step>
</Steps>

<Info>
  **Checkout como porta de entrada** — além do `POST /subscriptions`, uma assinatura pode nascer de
  um [link de Checkout](/pt-BR/checkout/links) com `mode=subscription`: o comprador paga a Session e
  a ativação da assinatura é **automática** após o pagamento — a 1ª fatura já nasce paga, sem nova
  cobrança. Com trial configurado, a assinatura nasce `trialing` e a cobrança do Checkout é apenas a
  **validação do cartão**, estornada automaticamente. A assinatura criada assim carrega o Link e a
  Session de origem no `metadata` — veja
  [Assinaturas via Checkout](/pt-BR/checkout/links#assinaturas-via-checkout).
</Info>

<Tip>
  Para testar ciclos sem esperar, use os recursos de simulação do sandbox. Veja
  [Sandbox: simular](/pt-BR/sandbox/simular) e [Ciclos e cobrança](/pt-BR/subscriptions/ciclos).
</Tip>

## Onde ficam os endpoints

São 21 rotas, e cada recurso mantém o mapa das suas — com os campos, os exemplos e o playground:

| Recurso                                       | O que se faz por lá                                                                          |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Planos e Preços](/pt-BR/subscriptions/plans) | monta o catálogo: o plano, os itens que o compõem e as versões de preço de cada um           |
| [Assinaturas](/pt-BR/subscriptions)           | cria o contrato e age sobre ele: pausa, retomada, cancelamento e troca de forma de pagamento |
| [Faturas](/pt-BR/subscriptions/invoices)      | acompanha o que cada ciclo emitiu — só leitura                                               |

Todas exigem o header `x-api-key`.

<Note>
  A criação e as ações aceitam o header opcional `Idempotency-Key`. Reenviar a mesma requisição com
  a mesma chave devolve o mesmo resultado, sem duplicar a operação. Veja
  [Convenções](/pt-BR/convencoes).
</Note>

## Ligar a fatura à transação

Toda cobrança da engine cria uma transação comum, das que aparecem em
[Transações](/pt-BR/transactions). Três marcas permitem reconciliar as duas pontas:

| Onde                                          | O quê                                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `transaction.referenceCode`                   | `billing:{invoiceId}:{chave de idempotência}`                                  |
| `transaction.additionalInfo.origin`           | `"billing"` — diz que a cobrança nasceu de uma fatura, não de uma venda avulsa |
| `transaction.additionalInfo.billingInvoiceId` | O `inv_` que originou a cobrança                                               |
| `transaction.additionalInfo.subscriptionId`   | O `sub_` da assinatura dona da fatura                                          |

O mesmo par `origin`/`billingInvoiceId` vai no `additionalInfo` de cada pagamento da transação.

<Warning>
  **Nenhuma das três é garantia.** `referenceCode` e `additionalInfo` são campos de entrada do
  `POST /transactions` — uma transação criada por você pode ter exatamente os mesmos valores. Elas
  servem para **reconhecer** uma cobrança da engine no meio das suas, não para provar de onde ela
  veio.

  **Para saber se uma fatura foi paga, pergunte à fatura**, não à transação:
  [`GET /invoices/{id}`](/pt-BR/subscriptions/invoices) responde com `status`, `paidAt`, `amountPaid`
  e `amountRemaining`. Use a transação quando quiser os detalhes do processamento — gateway,
  parcelas, código de autorização.
</Warning>

## Primeiro contato (sandbox)

Um `GET` rápido para confirmar que a sua chave de sandbox alcança a API e lista as
assinaturas existentes (a lista vem vazia se você ainda não criou nenhuma).

```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/subscriptions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```

Resposta (lista paginada):

```json theme={null}
{
  "data": [
    {
      "id": "sub_eg1jei80u0wtxvg81x7z48iv6",
      "customerId": "cust_h4ro15pocv8wt9lzikxxg1bq3",
      "status": "active",
      "currency": "BRL",
      "collectionMethod": "charge_automatically",
      "nextInvoiceAt": "2026-07-24T12:00:00.000-03:00"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```

<Warning>
  Os campos e o formato exato da resposta de cada recurso estão documentados nas páginas de
  referência específicas. A resposta acima é ilustrativa para você reconhecer a forma da lista
  paginada — confira [Assinaturas](/pt-BR/subscriptions) para o objeto completo.
</Warning>

## Erros

Estes endpoints seguem o mesmo padrão de erro do resto da API. Status comuns nesta seção:

* `404` — recurso não encontrado (assinatura, plano, preço ou cliente inexistente).
* `409` — operação inválida para o estado atual (ex.: cancelar uma assinatura já cancelada,
  retomar uma assinatura que não está pausada, ou conflito de validação ao criar).
* `400` — corpo inválido (ex.: campos obrigatórios ausentes ou combinação proibida de campos).

Formato completo e tabela de códigos em [Erros](/pt-BR/erros).

## Veja também

<CardGroup cols={2}>
  <Card title="Planos e Preços" icon="tags" href="/pt-BR/subscriptions/plans">
    Monte o catálogo da sua oferta recorrente.
  </Card>

  <Card title="Assinaturas" icon="repeat" href="/pt-BR/subscriptions">
    Crie, cancele, pause e retome contratos.
  </Card>

  <Card title="Faturas" icon="receipt" href="/pt-BR/subscriptions/invoices">
    Consulte as cobranças geradas a cada ciclo.
  </Card>

  <Card title="Ciclos e cobrança" icon="calendar-clock" href="/pt-BR/subscriptions/ciclos">
    Entenda geração de fatura, cobrança e avanço de ciclo.
  </Card>

  <Card title="Clientes" icon="user" href="/pt-BR/customers">
    A assinatura sempre aponta para um cliente.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt-BR/webhooks/eventos">
    Assine os 17 eventos `subscription.*` e `invoice.*` (ex.: `invoice.paid`,
    `subscription.past_due`). Nem toda mudança de status gera evento — `completed` e
    `incomplete_expired` não têm webhook próprio.
  </Card>
</CardGroup>