Skip to main content
O plano é o “produto” da assinatura: diz quanto custa, em que moeda e de quanto em quanto tempo o cliente é cobrado. Cada assinatura nasce de um plano. Um mesmo plano atende quantos assinantes você tiver.
Para o negócio: o time comercial ou de produto define os planos (ex.: Básico mensal R$ 49,90, Premium mensal R$ 99,90, Anual com desconto) e o time técnico os cadastra uma vez. Alterar o preço de um plano vale só para quem assinar depois: os assinantes atuais continuam com o preço contratado. Para mudar o preço de quem já assina, é preciso cancelar a assinatura e criar outra.

Quando usar

Como funciona

1

Crie o plano

Defina nome, preço, moeda BRL, recorrência e, se quiser, trial e mensagem ao comprador.
2

Opcional: envie a imagem

A imagem aparece em imageUrl nas consultas do plano.
3

Use o plano nas assinaturas

Envie o id do plano em subscriptionPlanId ao criar cada assinatura.
4

Ajuste ou desative quando precisar

Atualizações e desativação afetam só as novas assinaturas.

Regras de negócio

Mudar o preço de um plano não reajusta os assinantes atuais. Se a sua estratégia é reajustar a base, o caminho é cancelar a assinatura de cada cliente e criar uma nova no plano atualizado, com nova cobrança imediata. Planeje a comunicação com o cliente antes.

Tipos de recorrência

Para recorrência personalizada, informe recurrenceInterval em dias:
Esse plano cobra a cada 90 dias.
O intervalo custom conta dias corridos. custom com 30 não é igual a monthly: o mensal mantém o dia do mês da contratação, e o custom só soma dias, então a data da cobrança desliza conforme o calendário. Da mesma forma, “a cada 60 dias” não é “bimestral no mesmo dia do mês”. Se o cliente espera ser cobrado sempre no mesmo dia do mês, use monthly. Nos tipos weekly, biweekly e monthly, recurrenceInterval é ignorado.

Trial (período de teste)

O plano pode ter um período de teste, grátis ou pago, configurado no objeto trial:

Como cada caso se comporta na criação da assinatura

O desenho abaixo mostra o caminho de cada caso, da criação da assinatura até a primeira cobrança cheia. Ao fim do trial, a primeira cobrança cheia é processada no ciclo normal. Em planos com trial, a ativação e a primeira cobrança cheia geram os webhooks subscription.activated e subscription.renewed, com o objeto trial no payload.

Validação de R$ 1,00 no trial grátis

No trial grátis, o comprador pode ver duas linhas na fatura: a cobrança de R$ 1,00 e o estorno. Avise-o no checkout (por exemplo: “Para validar o seu cartão, faremos uma cobrança de R$ 1,00 que será estornada em seguida”).
  • A validação só acontece em plano com trial grátis, quando a assinatura é criada sem skipTrial: true. O estorno do R$ 1,00 é assíncrono.
  • Se a validação for recusada, ficar em análise ou o processador não responder, a resposta é 422 com { "code": "CARD_VALIDATION_FAILED", "message": "Não foi possível validar o cartão: <motivo>" }, e nada é criado: nem assinatura, nem webhook. Se ficou em análise, oriente o comprador a usar outro cartão.
  • 409 CARD_VALIDATION_IN_PROGRESS: já há uma validação do mesmo cartão em andamento (requisição repetida em paralelo).
  • 429 CARD_VALIDATION_RATE_LIMITED: 3 recusas do mesmo cartão em 24 horas, ou 30 recusas na mesma conta em 1 hora.
  • Os três erros vêm no formato { code, message }. Decida o fluxo pelo code e use a message só para exibir.
  • Se a mesma requisição (mesmo merchant, cliente, cartão e plano) for reenviada em até 15 minutos, a API reaproveita a validação aprovada e não cobra o R$ 1,00 de novo. A resposta 201 traz cardValidation: { "validated": true, "amount": 1 }.
  • A cobrança de validação e o estorno dela não geram webhooks.
Para o desenvolvedor: se a criação falhar por outro motivo depois da validação (por exemplo, um erro de rede na sua aplicação), repita a mesma requisição dentro de 15 minutos. Assim o cliente não é cobrado de novo pela validação.

Status do plano

Desativar um plano não afeta as assinaturas existentes, que continuam sendo cobradas normalmente. O desenho abaixo mostra como o plano muda de status, com a confirmação que a desativação sempre exige.

Passo a passo

1. Criar o plano

A resposta 201 traz só o id do plano. Para ver o plano completo, use a consulta.
Erros específicos da criação: 404 Merchant not found (o merchantId não é de uma conta a que a chave tem acesso), 404 Currency not found (moeda inexistente) e 400 Invalid payment methods: ... (método desconhecido em paymentMethods).

Exemplos de planos

2. Consultar e listar planos

cURL
activeSubscriptionsCount mostra quantas assinaturas ativas o plano tem, útil para o time de negócio acompanhar a base de cada plano. A listagem GET /v1/subscription-plans é paginada e aceita merchantId, status (active ou inactive), page (padrão 1) e size (padrão 10). A resposta traz data e meta (total, page, limit, totalPages).
cURL
Existe ainda a listagem de cobranças do plano, GET /v1/subscription-plans/{id}/charges. Cada item traz id (o registro de cobrança da assinatura), chargeId (o id da cobrança, usado em GET /v1/charges/{id}), subscriptionId e billingCycle. É o caminho para relacionar o histórico de Consultar assinatura às cobranças. chargeId vem null quando a tentativa nem chegou ao processador.
Para o desenvolvedor: antes de levar o cliente ao checkout, consulte o plano e confirme que status é active. Um plano inativo faz a criação da assinatura falhar com 404 Subscription plan not found or inactive.

3. Enviar a imagem do plano

A imagem é enviada como arquivo (multipart/form-data, campo file), em PNG, JPG ou JPEG. A resposta é 204, sem corpo.
cURL
Depois do envio, a URL da imagem aparece em imageUrl na consulta do plano.

4. Atualizar o plano

PUT /v1/subscription-plans/{id} exige merchantId e aceita os demais campos que você quer mudar: name, price, currency, recurrenceType, recurrenceInterval, endDate, buyerMessage, paymentMethods e trial. Para remover o trial, envie "trial": null.
cURL
A resposta 200 traz só o id do plano. Para conferir as alterações, consulte o plano. As mudanças valem só para novas assinaturas.

5. Desativar o plano

A desativação é feita em duas etapas. A primeira chamada sempre pede confirmação, tenha o plano assinaturas ativas ou não. Essa rota nunca devolve o objeto do plano.
1

Solicite a desativação

cURL
Resposta:
O token vale 5 minutos e é de uso único. Pedir a desativação de novo gera outro token e invalida o anterior.
2

Confirme em até 5 minutos

cURL
Resposta 204, sem corpo. O plano fica inactive. Token errado, vencido ou já usado: 400 Invalid or expired confirmation token. Plano inexistente ou de outra conta: 404 Subscription plan not found.
Para o negócio: a confirmação existe para evitar desativações por engano. Se a sua equipe opera planos por um painel interno, mostre a quantidade de assinaturas ativas (activeSubscriptionsCount, na consulta do plano) antes de confirmar. Lembre que desativar não cancela ninguém: os assinantes atuais continuam renovando normalmente. Para encerrá-los, é preciso cancelar uma a uma.
Para reativar, envie "status": "active" para a mesma rota. A resposta é { "requiresConfirmation": false } e o plano é ativado imediatamente.

Erros comuns

Perguntas frequentes

Sim. Cada plano é independente e cada assinatura aponta para um plano.
Nada. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Só novas assinaturas usam o preço atualizado.
Não. As assinaturas existentes continuam ativas e renovando normalmente. O plano só deixa de aceitar novas assinaturas. Para encerrar as assinaturas, cancele uma a uma.
Pode ver duas linhas na fatura: a cobrança e o estorno. A documentação orienta avisar o comprador no checkout.
O trial é configurado no plano. Para um cliente específico pular o trial, crie a assinatura com skipTrial: true, o que cobra o valor cheio imediatamente. Para oferecer trial só a um grupo, crie um plano separado com trial.

Como testar

A criação do plano não movimenta dinheiro. As assinaturas criadas a partir dele são reais mesmo com a chave de teste.

Veja também

Assinaturas: visão geral

O fluxo completo da assinatura.

Ciclo de vida

Status, retentativa e cancelamento.

Criar plano

Contrato completo da rota.

Alterar status do plano

Ativar e desativar planos.