Alterar uma assinatura
Reajuste o valor de quem já assina ou atualize o metadata de uma assinatura, sem mudar o plano nem as outras assinaturas dele.
Altere a assinatura
curl -X PATCH https://api.sandbox.payzu.dev/v1/subscriptions/sub_EG9uphTcCTMvYBkHPKr4cc \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Content-Type: application/json" \
-d '{
"amount": 16990,
"metadata": {
"internal_id": "5678"
}
}'{
"id": "sub_EG9uphTcCTMvYBkHPKr4cc",
"code": "EELBD9PE",
"status": "active",
"name": "Plano Mensal",
"amount": 16990,
"recurrence": "monthly",
"payment_method": "credit_card",
"updated_at": "2026-11-11T15:40:12.007Z",
"plan": {
"id": "plan_oOsn4Cs4eayZ3LoytwzErn",
"name": "Plano Mensal"
},
"metadata": {
"internal_id": "5678"
}
}Referência: Alterar uma assinatura
Envie só o que muda. Campo fora dos três abaixo responde 400.
| Campo | Status da assinatura | Regra |
|---|---|---|
amount | active | Novo valor de cada ciclo, em centavos, de no mínimo 500 (R$ 5,00). |
credit_card.card_id | active | Um cartão salvo do mesmo cliente. A troca de cartão ainda não está disponível na assinatura no cartão, e a assinatura no Pix não tem cartão: nos dois casos, a chamada é recusada. |
metadata | active ou canceled | Substitui o mapa inteiro, com os limites de Metadados. |
- Cobranças já geradas: o valor novo vale para as cobranças ainda não geradas e entra na próxima fatura, com o desconto que ainda estiver em vigor.
- Desconto em vigor: se ele deixa o próximo ciclo abaixo de
500, a PayZu recusa o valor novo. - Cartão: a PayZu atualiza o valor na adquirente antes de gravar. Se a adquirente não aceitar, nada muda.
- Assinatura
incomplete: ometadatanão muda enquanto a adesão espera o pagamento, porque é ele que identifica a adesão que uma nova criação aproveita.
Alterar o plano não muda quem já assina.
A assinatura guarda o nome, o valor e a periodicidade da adesão. Para reajustar várias assinaturas, altere cada uma por esta rota.
Confirme a alteração
A resposta 200 traz a assinatura inteira, já alterada, e sai subscription.updated, com o corpo de Assinatura alterada.
Um corpo sem nenhum dos três campos recebe a assinatura como está e não envia evento. Para conferir depois, consulte a assinatura.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ503 | 400 | O valor da assinatura, com o desconto em vigor, precisa ser de no mínimo R$ 5,00. |
| - | 404 | Assinatura não encontrada para o id informado. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
PZ501 | 409 | Só uma assinatura ativa pode ter o valor ou o cartão alterado. |
PZ502 | 409 | O metadata não pode ser alterado enquanto a assinatura aguarda o pagamento inicial. |
PZ504 | 422 | A assinatura é paga por Pix e não tem cartão. |
PZ505 | 422 | A troca de cartão de assinatura no cartão ainda não está disponível. |
PZ506 | 503 | Não foi possível atualizar o valor da assinatura agora. Tente de novo. |
O amount abaixo de 500 responde 400, com amount em fields. Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.