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
Tipos de recorrência
Para recorrência personalizada, informe
recurrenceInterval em dias:
Trial (período de teste)
O plano pode ter um período de teste, grátis ou pago, configurado no objetotrial:
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
- 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 é
422com{ "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 pelocodee use amessagesó 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
201trazcardValidation: { "validated": true, "amount": 1 }. - A cobrança de validação e o estorno dela não geram webhooks.
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.
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
- Mensal com trial grátis
- Semanal com trial pago
- Trimestral com data de término
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
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.
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
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
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
2
Confirme em até 5 minutos
cURL
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."status": "active" para a mesma rota. A resposta é { "requiresConfirmation": false } e o plano é ativado imediatamente.
Erros comuns
Perguntas frequentes
Posso ter vários planos ativos ao mesmo tempo?
Posso ter vários planos ativos ao mesmo tempo?
Sim. Cada plano é independente e cada assinatura aponta para um plano.
Mudei o preço do plano. O que acontece com quem já assina?
Mudei o preço do plano. O que acontece com quem já assina?
Nada. Preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação. Só novas assinaturas usam o preço atualizado.
Desativar um plano cancela as assinaturas?
Desativar um plano cancela as assinaturas?
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.
O cliente vai ver a cobrança de R$ 1,00 do trial grátis?
O cliente vai ver a cobrança de R$ 1,00 do trial grátis?
Pode ver duas linhas na fatura: a cobrança e o estorno. A documentação orienta avisar o comprador no checkout.
Posso dar trial só para alguns clientes?
Posso dar trial só para alguns clientes?
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.

