Status
Renovações
Quando o período de cobrança termina, assinaturasactive e trialing são renovadas: a Pagou cobra o cartão ou, no Pix Automático, o banco do pagador debita o valor autorizado. Renovações bem-sucedidas emitem subscription.started após um teste ou subscription.renewed nos ciclos seguintes.
Pagamentos com falha
failure_policy controla o que acontece depois de uma renovação com falha no cartão:
retry_then_cancel: passa pelas retentativas antes do cancelamento.immediate_cancel: cancela quando a renovação não puder ser cobrada.
retry_offsets_days apenas quando precisar definir intervalos explícitos de retentativa.
No Pix Automático, o intervalo entre tentativas não é configurável e retry_offsets_days não tem efeito. Veja como funcionam os débitos com falha em Assinaturas com Pix Automático.
Troca de plano
A troca de plano vale para assinaturas com cartão. Numa assinatura com Pix Automático,PATCH com product_id retorna 422 e o plano não muda (PLAN_CHANGE_UNAVAILABLE_FOR_PAYMENT_METHOD quando a assinatura está vinculada a um plano do catálogo).
PATCH /v2/subscriptions/{id} com um product_id move uma assinatura com cartão para outro plano da mesma família de produtos.
Subir de nível é cobrado na hora, pelo que resta do período, e mantém a data de renovação. Descer de nível numa assinatura active é agendado: nada é cobrado, nada é estornado, e o novo plano passa a valer em current_period_end. Uma troca entre planos de ciclos de cobrança diferentes é sempre imediata, pelo valor cheio, e reinicia a data de renovação.
Enquanto há uma troca agendada, pendingChange guarda o plano de destino, o valor que a renovação vai cobrar — o plano mais o que for cobrado junto dele — e a data em que ela se aplica. A renovação seguinte cobra o novo plano e limpa o pendingChange. Envie o product_id do plano atual para cancelar uma troca agendada.
O status não muda por causa de uma troca de plano, com uma exceção: uma assinatura em past_due que liquida o ciclo em aberto pelo valor cheio do novo plano volta para active.
Cancelamento
Cartão:POST /v2/subscriptions/{id}/cancel agenda o cancelamento para o fim do período atual. A assinatura fica cancel_scheduled imediatamente, emite subscription.updated e depois muda para canceled.
Pix Automático: o cancelamento é imediato e emite subscription.canceled. A resposta vem já canceled ou mantém o status atual com recurringAuthorization.status: "cancel_pending" até o cancelamento ser confirmado. Veja Assinaturas com Pix Automático.