Skip to main content
PATCH
Esta rota atualiza as informações livres (metadata) de uma assinatura ativa, como o ID do usuário no seu sistema, a campanha de origem ou uma observação do atendimento. Cartão, plano, valor e pausa não podem ser alterados aqui nem em nenhuma outra rota.

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).
  • A assinatura precisa estar com status active. Nos demais status a resposta é 400. Esta rota não serve para destravar uma assinatura pending_activation.
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.
Não existe troca de cartão, troca de plano, alteração de valor nem pausa. Para trocar o cartão ou o plano, cancele a assinatura e crie outra. A nova assinatura começa um ciclo novo, com cobrança imediata. Leve isso em conta: o cliente pode pagar o novo ciclo antes do fim do período já pago da assinatura anterior.

Parâmetros de caminho

string
required
Identificador único da assinatura. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.

Corpo da requisição

Apenas metadata pode ser atualizado.
object
Informações suas, em formato livre, guardadas na assinatura. Ex.: {"notes": "Cliente VIP"}.

Respostas

boolean
Indica se a atualização foi feita. Ex.: true.
string
ID da assinatura. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.
object
metadata atualizado. Ex.: {"notes": "VIP customer"}.
Para o negócio: o metadata da assinatura volta nos webhooks de assinatura (campo data.metadata) e na consulta da assinatura. Gravar ali o identificador do cliente no seu sistema facilita a conciliação de cada evento com a conta certa.
Para o desenvolvedor: a documentação não diz se o metadata enviado é mesclado ao existente ou se o substitui. Para não perder chaves, consulte a assinatura, monte o objeto completo e envie tudo de uma vez.

Erros comuns

Veja também

Ciclo de vida

Status, renovação, retentativas e cancelamento.

Visão geral de assinaturas

Fluxo completo, do cliente à cobrança recorrente.

Planos

Recorrência, trial e status do plano.

Webhooks de assinatura

Eventos enviados a cada etapa da assinatura.

Registrar cartão

Registre o novo cartão antes de recriar a assinatura.

Cancelar assinatura

Primeiro passo para trocar cartão ou plano.