Guia de Assinaturas

Confira o guia de assinaturas para mais informações.

Endpoint responsável por atualizar as configurações de uma assinatura existente, como forma de pagamento, periodicidade, valor, vencimento, descontos, multas, juros e demais configurações da recorrência.

As alterações realizadas impactam apenas a assinatura informada e, dependendo dos parâmetros enviados, podem afetar somente cobranças futuras ou também cobranças pendentes já geradas.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• alterar o valor da assinatura;
• modificar a forma de pagamento;
• atualizar a periodicidade da recorrência;
• alterar o vencimento das próximas cobranças;
• suspender ou reativar uma assinatura;
• atualizar configurações comerciais da recorrência.

Parâmetros importantes

Além dos campos documentados automaticamente nesta referência, alguns parâmetros possuem impacto direto no comportamento da assinatura:

• nextDueDate — define o vencimento da próxima cobrança que será gerada, não alterando cobranças já existentes.
• updatePendingPayments — quando enviado como true, aplica as alterações suportadas também às cobranças pendentes já geradas.
• status — permite suspender (INACTIVE) ou reativar (ACTIVE) a assinatura.
• billingType — altera a forma de pagamento das próximas cobranças.
• cycle — altera a periodicidade da recorrência.

Regras de negócio importantes

Ao atualizar uma assinatura, considere que:

• o campo nextDueDate altera apenas a próxima cobrança ainda não gerada;
• cobranças já criadas permanecem inalteradas por padrão;
• alterações de valor e forma de pagamento afetam somente cobranças futuras;
• para atualizar cobranças pendentes já existentes, envie updatePendingPayments: true.

Caso esse parâmetro não seja informado, as cobranças pendentes manterão suas configurações originais.

Suspensão e reativação da assinatura

É possível interromper temporariamente a geração de novas cobranças alterando o status para INACTIVE.

Durante esse período:

• nenhuma nova cobrança será criada;
• cobranças já existentes permanecem inalteradas;
• a assinatura continuará cadastrada normalmente.

Para reativá-la:

• altere o status para ACTIVE;
• informe obrigatoriamente um novo nextDueDate, que será utilizado como vencimento da próxima cobrança da recorrência.

Comportamentos importantes

Após uma atualização bem-sucedida:

• a assinatura passa a utilizar imediatamente as novas configurações;
• cobranças futuras seguirão os novos parâmetros enviados;
• cobranças já geradas somente serão alteradas quando updatePendingPayments for informado como true;
• suspender uma assinatura não remove cobranças existentes.

Boas práticas

Erros comuns

400 Bad Request

Pode ocorrer quando algum parâmetro possui formato inválido ou quando a combinação de campos enviados não é permitida.

401 Unauthorized

Ocorre quando a API Key é inválida ou pertence a outro ambiente.

404 Not Found

Ocorre quando a assinatura informada não existe ou não pertence à conta autenticada.

Impactos operacionais

A atualização de uma assinatura pode modificar o comportamento das cobranças futuras e, opcionalmente, das cobranças pendentes.

Por esse motivo, recomenda-se validar cuidadosamente quando utilizar updatePendingPayments, especialmente em integrações que realizam conciliação financeira, notificações automáticas ou sincronização com sistemas externos.

Conteúdos relacionados

• Criar assinatura
• Recuperar uma única assinatura
• Listar assinaturas
• Listar cobranças de uma assinatura
• Atualizar cartão de crédito da assinatura
• Webhooks de assinatura