Skip to main content
POST
O plano é o “produto” que o seu cliente assina: ele define quanto cobrar, em que moeda e de quanto em quanto tempo. Toda assinatura nasce a partir de um plano, então esta é a primeira rota que você chama ao montar uma oferta recorrente, como uma mensalidade de software, um clube de assinatura ou uma escola com cobrança mensal.

Quando usar

Antes de chamar

  • Tenha uma chave secreta gerada por usuário com a permissão criar assinaturas. Nos perfis padrão, são Owner, Manager e Operador. Os perfis Visualizador, Desenvolvedor e Financeiro recebem 403 (veja Permissões por perfil).
  • Tenha o merchantId da conta que vai vender o plano.
  • Defina a periodicidade e, se houver, as regras do trial. O preço e a periodicidade ficam congelados em cada assinatura no momento da contratação: editar o plano depois só vale para assinaturas novas.
Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste, inclusive a validação de R$ 1,00 do trial grátis. Veja como homologar em Assinaturas: visão geral.
O valor vai em reais: "price": 99.9 significa R$ 99,90. Planos cobrados no cartão aceitam apenas a moeda BRL.

Corpo da requisição

Campos obrigatórios: merchantId, name, price, currency e recurrenceType.
string
required
ID do merchant que vai vender o plano. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.
string
required
Nome do plano. Ex.: Plano Premium Mensal.
number
required
Preço cobrado a cada ciclo, na unidade da moeda (ex.: 99.90 = R$ 99,90).
string
required
Código da moeda no padrão ISO 4217. Ex.: BRL. Planos cobrados no cartão aceitam apenas BRL.
string
required
Periodicidade da cobrança:
integer
Intervalo da recorrência personalizada, em dias corridos. Inteiro maior que zero, obrigatório quando recurrenceType é custom. Ex.: 90 (cobrança a cada 90 dias). Nos tipos weekly, biweekly e monthly, o campo é ignorado.
custom com 30 não é igual a monthly. O mensal mantém o dia do mês da contratação; o custom só soma dias, e a data da cobrança desliza conforme o calendário. Para cobrar todo mês no mesmo dia, use monthly.
string
Data de término do plano, no padrão ISO 8601 (formato date). Ex.: 2025-12-31. Quando o período seguinte de uma assinatura começaria depois dessa data, a assinatura é encerrada com status expired.
string
Mensagem exibida ao comprador. Ex.: Bem-vindo ao Plano Premium!.
string[]
Formas de pagamento aceitas. Ex.: ["credit_card"].
object
Período de trial (teste) opcional. Quando informado, os novos assinantes passam pelo trial antes do primeiro ciclo cobrado com o valor cheio.
string
default:"active"
Status inicial do plano: active (aceita novas assinaturas) ou inactive (não aceita).

Como o trial afeta a primeira cobrança

Ao fim do trial, a primeira cobrança cheia é processada no ciclo normal de cobrança.
Para o negócio: no trial grátis, o comprador pode ver na fatura do cartão duas linhas de R$ 1,00 (a cobrança de validação e o estorno, que é feito logo depois, de forma assíncrona). Avise o comprador disso no checkout. Se a validação for recusada, ficar em análise ou o processador não responder, a assinatura não é criada e a API responde 422 CARD_VALIDATION_FAILED.

Respostas

A resposta 201 traz só o id do plano. Para ver o plano completo, chame Consultar plano.
string
Identificador único do plano. Guarde este valor: ele vai em subscriptionPlanId ao criar a assinatura.

Exemplos por caso de uso

Plano mensal de um software de gestão, sem trial.

Erros comuns

Veja também

Planos

Recorrência, trial e status do plano.

Visão geral de assinaturas

Fluxo completo, do cliente à cobrança recorrente.

Ciclo de vida

Status, renovação, retentativas e cancelamento.

Webhooks de assinatura

Eventos enviados a cada etapa da assinatura.

Registrar cartão

Guarde o cartão no cofre antes de criar a assinatura.

Criar assinatura

Vincule um cliente ao plano e faça a primeira cobrança.