Trocar de plano e cancelar

Trocar de plano

Crie a nova subscription com "replaces": o id da subscription atual. Quando a nova fica ativa, o broker cancela a antiga na hora; se o cliente abandona o checkout, nada muda.

{ "amount": "99.00", "currency": "BRL", "interval": "month", "replaces": "<current subscription id>", … }

Cancelar

{ "at_period_end": true }

at_period_end é true por padrão; envie false para encerrar agora. A chamada responde 202 Accepted na hora:

{
  "id": "…",
  "status": "active",
  "cancel_requested_at": "2026-09-23T21:17:22Z",
  "cancel_at": "2026-10-23T00:00:00Z",
  "links": { "self": "https://pay.contagorda.com/api/v1/subscriptions/…" }
}

1. 1status responde "o cliente tem acesso?": fica active até a subscription terminar de fato.
2. 2cancel_at diz quando ("seu plano termina em …"); volta a null se o cliente desistir do cancelamento.
3. 3Webhooks: subscription.canceling quando o pedido é aceito, subscription.canceled quando termina.
4. 4Um cancelamento agendado no próprio dashboard do gateway não envia subscription.canceling: chega como subscription.updated com cancel_at preenchido.

Desfazer um cancelamento

Até chegar o cancel_at, o cliente pode manter o plano: a mesma subscription continua renovando no mesmo dia e no mesmo cartão, sem novo checkout e sem segunda cobrança. A chamada responde 202 Accepted com a subscription, cancel_at de volta a null, e o app recebe subscription.resumed. Um cancelamento que encerra a subscription agora não pode ser desfeito.