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.
Todos os endpoints desta página exigem o header
x-api-key. Veja Autenticação.
Os exemplos usam a base URL de sandbox https://api.sandbox.z2pay.com/v1.Endpoints
O plano nasce pronto para vender:POST /plans cria os itens, o preço de cada um e publica, tudo
na mesma chamada.
Status do plano
Quem determina o status é você, pelas ações acima e pelo painel — nunca a Z2Pay sozinha. Pela API o plano nasceactive e percorre active ⇄ inactive → archived.
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".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 issorecurrence 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
Assinaturas
Como instanciar um plano para um cliente e o que muda depois de contratado.
Faturas
O que a Z2Pay emite a cada ciclo, e como acompanhar a cobrança.
Ciclos
Como a cadência, as âncoras e a antecedência da cobrança decidem as datas.
Visão geral de assinaturas
O panorama dos quatro recursos e por onde começar a integrar.