Skip to main content

Mudanças de Itens da Assinatura

Além das mudanças de plano (upgrade/downgrade), o Faturamento Automático suporta mudanças nos itens individuais de uma assinatura — alterar quantidades, adicionar add-ons, trocar um produto avulso ou um item metered sem precisar trocar o plano principal. A tela /dashboard/subscription-changes agrupa o histórico dessas mudanças e a configuração padrão de proration.

Aba Histórico​

Mostra todas as mudanças de itens registradas na organização. Cada linha corresponde a um registro de SubscriptionItemChange e exibe:

  • ID da assinatura afetada
  • Status: pending, scheduled, completed, canceled ou failed
  • Timing: immediate (aplica agora) ou end_of_period (aplica no próximo ciclo)
  • Mudanças: itens adicionados, removidos ou alterados (com quantidade e preço)
  • Crédito gerado (proration_credit_subcents) e cobrança gerada (proration_charge_subcents)
  • Data efetiva e data de criação

As mudanças completed já foram processadas; scheduled aguardam o worker da renovação executar na virada do ciclo.

Aba Configuração​

Define o comportamento padrão quando um item é adicionado, removido ou tem quantidade alterada:

  • Permitir aumento de quantidade e permitir redução — controla quem pode alterar o que.
  • Timing padrão — quando a mudança é aplicada (imediata ou no fim do período).
  • Método de proration — full_proration, partial_proration ou no_proration.
  • Crédito em redução — se gera saldo na conta do cliente ao reduzir quantidade.
  • Reembolso em redução — se devolve via gateway em vez de gerar crédito.

A configuração é resolvida por organização e pode ser sobrescrita por regras específicas no momento da mudança via API.

Diferença entre mudança de itens e mudança de plano​

CenárioTela
Trocar de Starter para GrowthMudança de Plano
Adicionar 10 usuários extras ao plano atualMudanças de Itens
Trocar add-on Email Premium por SMS PremiumMudanças de Itens
Reduzir quantidade de licenças no fim do cicloMudanças de Itens

Ambos os fluxos geram proration quando aplicável, e ambos disparam eventos e webhooks (subscription.updated, subscription_item.changed).

Captura de tela​

Histórico e configuração de mudanças de itens de assinatura