Skip to main content
PUT
Esta rota muda a configuração de um plano existente. Ela serve para reajustar o preço de venda, trocar o nome comercial, incluir ou remover um trial e mudar a mensagem ao comprador. Quem já assinou não é afetado: preço, moeda e periodicidade ficam congelados na assinatura no momento da contratação.

Quando usar

Antes de chamar

  • Tenha uma chave secreta gerada por usuário com a permissão atualizar 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 id do plano e o merchantId dono dele.
Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em Assinaturas: visão geral.
Editar o plano não altera assinaturas existentes. Se você reduzir o preço, os assinantes atuais continuam pagando o valor antigo. Comunique isso ao seu time comercial e de atendimento antes de anunciar um novo preço.

Parâmetros de caminho

string
required
Identificador único do plano. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.

Corpo da requisição

Campo obrigatório: merchantId. Os demais são opcionais: envie os que quer alterar.
string
required
ID do merchant dono do plano, usado na validação da requisição. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.
string
Nome do plano. Ex.: Plano Premium Atualizado.
number
Novo preço do plano, em reais. Ex.: 119.9 (R$ 119,90).
string
Código da moeda. Ex.: BRL. Planos cobrados no cartão aceitam apenas BRL.
string
Periodicidade: weekly (semanal), biweekly (quinzenal), monthly (mensal) ou custom (intervalo personalizado).
integer
Intervalo da recorrência personalizada, em dias corridos. Ex.: 90 (a cada 90 dias). Usado só quando recurrenceType é custom. Note que custom com 30 não é igual a monthly: o mensal mantém o dia do mês, e o custom só soma dias.
string
Data de término do plano (formato date). Ex.: 2025-12-31.
string
Mensagem exibida ao comprador.
string[]
Formas de pagamento aceitas. Ex.: ["credit_card"].
object | null
Configuração de trial para novas assinaturas. Envie null para remover o trial do plano.
Na criação do plano, durationDays e isFree são obrigatórios dentro de trial. No contrato desta rota, nenhum campo de trial é marcado como obrigatório. Para evitar ambiguidade, envie o objeto trial completo sempre que alterá-lo.

Respostas

A resposta 200 traz só o id do plano. Para ver o plano com as alterações, chame Consultar plano.
string
Identificador único do plano.
Para o negócio: um reajuste feito aqui cria duas tabelas de preço convivendo: a dos assinantes antigos (preço da contratação) e a dos novos (preço atualizado). A Finvia não migra assinantes de preço. Se a sua estratégia exige que todos paguem o novo valor, o caminho é cancelar a assinatura antiga e criar uma nova, com cobrança imediata e um ciclo novo.

Exemplos por caso de uso

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.

Alterar status do plano

Ative ou desative o plano para novas assinaturas.