> ## 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 > O contrato recorrente entre você e um cliente — como ele nasce, os dez estados por que passa e o que o move entre eles. Uma **assinatura** (`sub_`) é o contrato recorrente com um cliente: ela guarda o que se cobra, de quanto em quanto tempo e por qual forma de pagamento, e emite uma [fatura](/pt-BR/subscriptions/invoices) a cada ciclo. Pode ser instanciada a partir de um [plano](/pt-BR/subscriptions/plans) ou montada com itens avulsos, informados na criação. Todas as rotas exigem o header `x-api-key`. Veja [Autenticação](/pt-BR/autenticacao). Os exemplos usam a base URL de sandbox `https://api.sandbox.z2pay.com/v1`. *** ## Endpoints Cada endpoint tem a sua página, com os campos aceitos, os exemplos e o playground para testar. | Método | Rota | Descrição | | -------- | ----------------------------------------- | -------------------------------------------------------------------- | | `POST` | `/subscriptions` | [Cria uma assinatura](/pt-BR/subscriptions/create) | | `GET` | `/subscriptions` | [Lista as assinaturas](/pt-BR/subscriptions/list) | | `GET` | `/subscriptions/{id}` | [Busca uma assinatura por ID](/pt-BR/subscriptions/get) | | `POST` | `/subscriptions/{id}/payment-method` | [Troca a forma de pagamento](/pt-BR/subscriptions/payment-method) | | `POST` | `/subscriptions/{id}/change-plan` | [Troca o plano](/pt-BR/subscriptions/change-plan) | | `POST` | `/subscriptions/{id}/change-plan/preview` | [Simula a troca de plano](/pt-BR/subscriptions/change-plan-preview) | | `DELETE` | `/subscriptions/{id}/change-plan` | [Desfaz uma troca agendada](/pt-BR/subscriptions/change-plan-delete) | | `POST` | `/subscriptions/{id}/pause` | [Pausa a assinatura](/pt-BR/subscriptions/pause) | | `POST` | `/subscriptions/{id}/resume` | [Retoma a assinatura](/pt-BR/subscriptions/resume) | | `POST` | `/subscriptions/{id}/cancel` | [Cancela a assinatura](/pt-BR/subscriptions/cancel) | | `POST` | `/subscriptions/{id}/uncancel` | [Desfaz um cancelamento agendado](/pt-BR/subscriptions/uncancel) | A criação e as sete ações aceitam o header `Idempotency-Key` para repetir a requisição com segurança. Veja [Convenções](/pt-BR/convencoes). *** ## Como uma assinatura nasce **O estado inicial é consequência do que você envia, não uma escolha.** Não existe campo `status` na criação: a combinação de forma de pagamento, período de teste e adesão decide em que ponto do ciclo de vida a assinatura entra. A tabela dessa decisão está em [Criar assinatura](/pt-BR/subscriptions/create). O que importa aqui é o que distingue os três pontos de entrada: * **`active`** — há forma de pagamento e nada a esperar. A primeira fatura é emitida e cobrada. * **`trialing`** — há período de teste. A primeira fatura só nasce quando o teste acaba, **mesmo que a forma de pagamento já esteja cadastrada**. * **`incomplete`** e **`pending_enrollment`** — falta algo. A assinatura existe, mas ainda não cobra ciclo nenhum: na primeira falta a forma de pagamento; na segunda, o pagamento da adesão. *** ## Do `incomplete` ao `active` Uma assinatura `incomplete` existe mas **não tem como cobrar**. Só uma coisa a tira desse estado: anexar uma forma de pagamento por [`POST /subscriptions/{id}/payment-method`](/pt-BR/subscriptions/payment-method), que a ativa na hora e emite a primeira fatura. **A `incomplete` comum não expira.** Ela fica assim indefinidamente, até ganhar forma de pagamento ou ser cancelada à mão. A única com prazo é a que nasceu de um teste com `requiresPaymentMethod` e sem forma de pagamento: essa tem `incompleteExpiresAt` (cerca de 23 horas) e, vencido o prazo, vai para o estado terminal `incomplete_expired`. Isso significa que uma `incomplete` esquecida **não vira nada sozinha** — ela não some, não cancela e não cobra. Se a sua integração cria assinaturas sem forma de pagamento, é preciso acompanhá-las. **O link hospedado de troca de cartão não ativa uma `incomplete`.** Ele responde `409` nesse estado, porque existe para o cliente final trocar o cartão de uma assinatura **que já está ativa** — ver [Faturas](/pt-BR/subscriptions/invoices). Para o cliente final pagar e ativar, o caminho é o [Checkout](/pt-BR/checkout/links) com `mode: "subscription"`. *** ## Os dez estados | Status | O que significa | Como se sai dele | | -------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `incomplete` | Existe, mas sem forma de pagamento — não cobra | Anexar forma de pagamento (vira `active`), ou cancelar | | `incomplete_expired` | Prazo da `incomplete` de teste esgotado | Terminal | | `pending_enrollment` | Aguardando o pagamento da adesão; não cobra ciclos | Adesão paga (vira `active`); falha em definitivo ou janela vencida cancela | | `trialing` | Em período de teste | Fim do teste, com a primeira fatura paga | | `active` | Cobrando normalmente | Pausa, cancelamento, falha de cobrança, ou fim dos ciclos | | `past_due` | Cobrança falhou; a régua de inadimplência está tentando de novo | Retentativa paga volta a `active`; régua esgotada leva a `unpaid` ou `canceled` | | `unpaid` | Régua esgotada com a política `mark_unpaid` — cobrança abandonada | **Não é terminal**: o lojista reativa pelo painel, ou cancela | | `paused` | Suspensa; nada é cobrado | Retomada, manual ou na data agendada | | `canceled` | Encerrada | Terminal | | `completed` | Chegou ao fim dos `maxCycles` contratados | Terminal | **Nem todo estado tem rota que o produza.** `past_due`, `unpaid`, `completed`, `incomplete_expired` e a transição de `trialing` para `active` acontecem sozinhos, pelo motor de cobrança. Pela API você provoca pausa, retomada, cancelamento e a ativação de uma `incomplete` — o resto é consequência do que o tempo e os pagamentos fizerem. **`unpaid` não é o fim.** É o estado em que a cobrança automática desistiu, mas o contrato continua de pé: o lojista pode reativá-lo pelo painel, e a assinatura volta a `active` cobrando um ciclo novo. Uma integração que trate `unpaid` como terminal vai perder a reativação. A régua de inadimplência que move `past_due` está em [Ciclos](/pt-BR/subscriptions/ciclos). *** ## Veja também O catálogo de onde a assinatura é instanciada. O que a assinatura emite a cada ciclo. Cadência, âncoras e as datas de cada cobrança. Quem assina.