> ## 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.

# Planos e Preços

> Como o catálogo da oferta recorrente se organiza — o plano, os itens que ele reúne e as versões de preço de cada um.

Um **plano** (`plan_`) é o catálogo da sua oferta recorrente. Ele define a **cadência** — de quanto
em quanto tempo cobra — e reúne **itens** (`pli_`), cada um uma cobrança que aparece como linha na
fatura: `recurring` (todo ciclo) ou `activation` (uma vez, na adesão). Cada item tem uma ou mais
versões de **preço** (`price_`), sempre em centavos.

O preço é **versionado, e por isso o reajuste não alcança quem já assinou**: criar um preço novo
marca o anterior da mesma combinação (moeda, recorrência) como não-corrente, e ele passa a valer
para as próximas assinaturas. As que já existem seguem cobrando a versão que contrataram.

<Info>
  Todos os endpoints desta página 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`.
</Info>

***

## Endpoints

O plano nasce pronto para vender: `POST /plans` cria os itens, o preço de cada um e publica, tudo
na mesma chamada.

| Método   | Rota                                 | Descrição                                                                                           |
| -------- | ------------------------------------ | --------------------------------------------------------------------------------------------------- |
| `POST`   | `/plans`                             | [Cria um plano com seus itens, já publicado](/pt-BR/subscriptions/plans/create)                     |
| `GET`    | `/plans`                             | [Lista planos (paginado, com filtros)](/pt-BR/subscriptions/plans/list)                             |
| `GET`    | `/plans/:id`                         | [Busca um plano por ID, com os itens e o preço em vigor de cada um](/pt-BR/subscriptions/plans/get) |
| `PATCH`  | `/plans/:id`                         | [Atualiza campos editáveis do plano](/pt-BR/subscriptions/plans/update)                             |
| `POST`   | `/plans/:id/archive`                 | [Arquiva o plano](/pt-BR/subscriptions/plans/archive)                                               |
| `POST`   | `/plans/:id/items`                   | [Adiciona um item ao plano, com seu preço](/pt-BR/subscriptions/plans/items)                        |
| `PATCH`  | `/plans/:id/items/:itemId`           | [Atualiza um item](/pt-BR/subscriptions/plans/items-update)                                         |
| `DELETE` | `/plans/:id/items/:itemId`           | [Arquiva um item](/pt-BR/subscriptions/plans/items-delete)                                          |
| `GET`    | `/plans/:id/prices`                  | [Lista as versões de preço do plano](/pt-BR/subscriptions/plans/prices)                             |
| `POST`   | `/plans/:id/prices`                  | [Cria uma nova versão de preço](/pt-BR/subscriptions/plans/prices-post)                             |
| `POST`   | `/plans/:id/prices/:priceId/archive` | [Arquiva uma versão de preço](/pt-BR/subscriptions/plans/prices-archive)                            |

<Tip>
  Os POSTs aceitam o header opcional `Idempotency-Key` para repetir a requisição com segurança.
  Veja [Convenções](/pt-BR/convencoes).
</Tip>

***

## Status do plano

Quem determina o status é você, pelas ações acima e pelo painel — nunca a Z2Pay sozinha. Pela API o
plano nasce `active` e percorre `active` ⇄ `inactive` → `archived`.

| Status     | O que significa                                                           | Quando acontece                                                              |
| ---------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `draft`    | Criado sem itens; ainda não aceita assinaturas                            | Só pelo painel — `POST /plans` exige `items` e já publica                    |
| `active`   | Publicado; aceita novas assinaturas                                       | Na criação pela API, ou quando o lojista publica/reativa pelo painel         |
| `inactive` | Pausa **reversível**: não aceita novas assinaturas, mas continua editável | O lojista pausa o plano pelo painel. As assinaturas em curso seguem cobrando |
| `archived` | Encerrado para novas vendas, e imutável                                   | `POST /plans/:id/archive`. Não há como desarquivar                           |

<Note>
  **A transição `active` ⇄ `inactive` é do painel.** A API tem apenas `archive` — não existe
  `deactivate`/`reactivate` público. O valor `inactive` aparece nas respostas de `GET /plans` e é
  aceito no filtro `status`, então trate-o na sua integração mesmo sem poder produzi-lo: criar uma
  assinatura com um plano `inactive` responde `409` com `key: "errors.conflict.plan_not_active"`.
</Note>

***

## Quando o plano tem vários itens

**A cadência é do plano, não de cada item.** A assinatura tem um ciclo só — dois itens, um mensal e
outro anual, não teriam quando cobrar juntos. Por isso `recurrence` e `trialSpec` ficam na raiz do
plano, e o preço de cada item os herda no momento em que é criado. Os dois voltam na raiz de toda
resposta de plano, ao lado de uma cópia dentro de cada `currentPrice`.

**A `key` identifica o item para quem assina.** É o nome estável pelo qual a assinatura se refere
àquela linha da fatura — para informar outra quantidade, por exemplo. Por isso ela é única dentro
do plano.

**`activation` cobra uma vez, na adesão.** Não entra no ciclo: materializa na primeira fatura e não
reaparece nas seguintes. É o item para taxa de entrada, instalação ou setup — enquanto o
`recurring` é o que sustenta a assinatura mês a mês.

***

## Veja também

<CardGroup cols={2}>
  <Card title="Assinaturas" icon="repeat" href="/pt-BR/subscriptions">
    Como instanciar um plano para um cliente e o que muda depois de contratado.
  </Card>

  <Card title="Faturas" icon="file-text" href="/pt-BR/subscriptions/invoices">
    O que a Z2Pay emite a cada ciclo, e como acompanhar a cobrança.
  </Card>

  <Card title="Ciclos" icon="calendar" href="/pt-BR/subscriptions/ciclos">
    Como a cadência, as âncoras e a antecedência da cobrança decidem as datas.
  </Card>

  <Card title="Visão geral de assinaturas" icon="book-open" href="/pt-BR/subscriptions/visao-geral">
    O panorama dos quatro recursos e por onde começar a integrar.
  </Card>
</CardGroup>