Pular para o conteúdo principal
O Billing Engine da Z2Pay é o motor de cobrança recorrente da plataforma. Ele cria assinaturas que geram faturas a cada ciclo, e cada fatura cobrada vira uma transação no PSP (visível no dashboard com origem billing).
A API de Billing usa uma base URL própria, diferente da Core API. Nos exemplos desta seção a base é https://billing-api.sandbox.z2pay.com. A autenticação é a mesma do resto da plataforma: o header x-api-key com a sua chave de sandbox. Veja Autenticação e Ambientes.

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

Plano (Plan)

O catálogo da oferta recorrente: nome, código e os componentes que a compõem. Começa em draft, é publicado (active) e pode ser arquivado (archived).

Preço (Price)

Uma versão de preço de um componente do plano: define unitAmount (em centavos), currency e a recurrence (a cada quanto cobra). Versionado — criar um novo Preço desativa o anterior da mesma moeda/recorrência.

Assinatura (Subscription)

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.

Fatura (Invoice)

O documento de cobrança de um ciclo. Nasce de uma assinatura, é cobrada via PSP e transiciona entre open, paid, past_due, etc.
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.

​
Como os ciclos funcionam

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

Criação

Você cria a assinatura (POST /subscriptions). Se um defaultPaymentMethodRef for informado, ela nasce pronta para cobrar; sem método de pagamento, nasce incomplete.
2

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).
3

Cobrança

Com collectionMethod=charge_automatically (default), o Billing cobra o método de pagamento padrão. Cada cobrança vira uma transação no PSP com origin=billing. Com send_invoice, a fatura é apenas emitida para o cliente pagar.
4

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.
Para testar ciclos sem esperar, use os recursos de simulação do sandbox. Veja Sandbox: simular e Ciclos e cobrança.

​
Endpoints principais

Visão consolidada dos recursos de Billing. Cada grupo tem sua própria página de referência com os campos completos do corpo e exemplos. Todas as rotas exigem o header x-api-key.

​
Planos e Preços

MétodoRotaDescrição
POST/plansCria um plano (status inicial draft).
GET/plansLista planos (paginado, com filtros).
GET/plans/:idDetalha um plano.
PATCH/plans/:idAtualiza campos do plano.
POST/plans/:id/publishPublica o plano (draft → active).
POST/plans/:id/archiveArquiva o plano.
GET/plans/:id/templateRetorna o plano + componentes com o Preço atual de cada um.
GET/plans/:id/itemsLista os componentes do plano.
POST/plans/:id/itemsAdiciona um componente ao plano.
PATCH/plans/:id/items/:itemIdAtualiza um componente.
DELETE/plans/:id/items/:itemIdArquiva um componente.
GET/plans/:id/pricesLista as versões de Preço do plano.
POST/plans/:id/pricesCria uma nova versão de Preço.
POST/plans/:id/prices/:priceId/archiveArquiva uma versão de Preço.
POST/plans/:id/chargesCria componente + Preço inicial atomicamente.
Detalhes e campos: Planos e Preços.

​
Assinaturas

MétodoRotaDescrição
POST/subscriptionsCria uma assinatura.
GET/subscriptionsLista assinaturas (paginado, com filtros).
GET/subscriptions/:idDetalha uma assinatura.
GET/subscriptions/:id/itemsLista os itens ativos da assinatura.
POST/subscriptions/:id/cancelCancela (imediato ou ao fim do ciclo).
POST/subscriptions/:id/uncancelDesfaz um cancelamento agendado.
POST/subscriptions/:id/pausePausa a assinatura.
POST/subscriptions/:id/resumeRetoma uma assinatura pausada.
Detalhes e campos: Assinaturas.

​
Faturas

MétodoRotaDescrição
GET/invoicesLista faturas (paginado, com filtros).
GET/invoices/:idDetalha uma fatura.
GET/invoices/:id/line-itemsLista os itens de linha da fatura.
Detalhes e campos: Faturas.
Os endpoints de criação e de ação (POST .../publish, POST .../cancel, POST .../pause, etc.) 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.

​
Primeiro contato (sandbox)

Um GET rápido para confirmar que a sua chave de sandbox alcança a API de Billing e lista as assinaturas existentes (a lista vem vazia se você ainda não criou nenhuma). 
curl https://billing-api.sandbox.z2pay.com/subscriptions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta (lista paginada): 
{
  "data": [
    {
      "id": "sub_8KzQp2vR7nML3xY",
      "customerId": "cust_4Tg9hLm0bWqA",
      "status": "active",
      "currency": "BRL",
      "collectionMethod": "charge_automatically",
      "nextInvoiceAt": "2026-07-24T12:00:00.000-03:00"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}
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 para o objeto completo.

​
Erros

Os endpoints de Billing seguem o mesmo padrão de erro da plataforma. 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, pausar uma assinatura upfront, 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.

​
Veja também

Planos e Preços

Monte o catálogo da sua oferta recorrente.

Assinaturas

Crie, cancele, pause e retome contratos.

Faturas

Consulte as cobranças geradas a cada ciclo.

Ciclos e cobrança

Entenda geração de fatura, cobrança e avanço de ciclo.

Clientes

A assinatura sempre aponta para um cliente.

Webhooks

Receba notificações de fatura paga, falha de cobrança e mudanças de status.