MRR e seus movimentos, com NRR e GRR

Calcule o MRR de cada cliente no último dia do mês e compare com o último dia do mês anterior. Cada cliente-mês cai em um único movimento. O log bruto de mudanças conta idas e voltas dentro do mês e, numa base real, inflava o movimento em cerca de 18%. A foto do mês usa o último dia do mês para todos os segmentos, nunca o último dia em que cada segmento teve linha.

Churn é o cliente que tinha MRR no fim do mês anterior e termina o mês sem nenhuma assinatura vigente. Troca de plano, renovação ou troca de assinatura do mesmo cliente é expansão, contração ou nada. Migração de um produto para outro do mesmo cliente pode continuar contando como churn na origem e novo na destino na lente por produto, mas deve ser marcada à parte para não aparecer como perda de logo. Consolidação de grupo econômico segue a regra que o workspace já tem: se a regra é não consolidar, cada conta do billing é um cliente e só os grupos listados nas exceções são unidos.

Plano anual, semestral, trimestral ou de ciclo fora do padrão entra dividido pelos meses do ciclo (no Stripe, price.unit_amount x quantity dividido pelos meses de price.recurring.interval x interval_count). Preço com billing_scheme = tiered ou usage_type = metered não tem unit_amount, e a fórmula dá zero sem erro: valorize esse item pelo total das linhas da última fatura paga dele (um item por faixa gera várias linhas no mesmo período, some todas) ou some as faixas pela quantidade contratada. Antes de seguir, liste os itens de assinaturas vigentes que ficaram com MRR zero: a lista tem que vir vazia ou com cada caso explicado. Quando a fonte é a fatura, rateie o valor recorrente pelos meses de competência que ela cobre.

Implantação, setup, compra avulsa de créditos (preço one_time), prorations, serviços pontuais, taxas de marketplace e receita de parceiros ficam fora. Cobrança por uso (preço metered) só entra no MRR até o mínimo contratual; o uso variável acima dele vai para uma coluna própria de receita de uso, senão cada oscilação de consumo vira expansão ou contração. Desconto recorrente abate o MRR; declare a partir de quando um desconto temporário passa a contar (há quem só considere desconto aberto ou com mais de 3 meses).

Entram assinaturas active. Trialing não é MRR. Canceled e incomplete_expired saem, e o filtro é obrigatório porque a assinatura cancelada continua com itens e preço preenchidos. Past_due é uma decisão de negócio: o mais seguro é manter no MRR marcado como em risco até virar canceled ou unpaid. Quem tira past_due do MRR cria churn e reativação que não aconteceram quando a fatura é paga. Unpaid também é decisão declarada: diga se sai do MRR e confira com o critério do relatório do financeiro, que muitas vezes mantém unpaid, senão a conciliação não fecha. Congelamento aparece no Stripe como status paused ou pause_collection preenchido na assinatura: classifique como congelamento, não como churn.

Ao cancelar, o MRR atual do cliente vai a zero. O valor perdido é o MRR do cliente no fim do mês anterior, ou o último valor conhecido antes de canceled_at. MRR zero nunca significa cliente gratuito: significa cliente que saiu.

Cliente com MRR zero no fim do mês anterior e maior que zero agora é novo se nunca pagou e reativação se já teve MRR em algum mês anterior. Reativação não entra no NRR da coorte, porque o cliente não estava na base inicial.

Billing expõe o estado atual, e a API de eventos do Stripe só guarda os últimos dias. Mudança de quantidade ou de plano na mesma assinatura some. Grave uma foto diária das assinaturas e itens, ou um histórico com válido de e válido até, desde o primeiro dia. Para os meses antes do início do histórico, reconstrua pelas linhas de fatura pagas de preço recorrente, sem proration, contando cada linha no mês cujo último dia cai dentro do período de serviço dela (period.start até period.end). O primeiro mês com foto compara duas fontes diferentes: marque-o como mês de emenda e não leve o movimento dele ao board.

Depois do fechamento, grave o resultado do mês numa versão provisória e permita uma única correção, que vira final. Correções retroativas posteriores entram como ajuste no mês em que foram descobertas, com o mês de referência registrado, nunca reescrevendo o número já reportado.

Converta tudo para a moeda de reporte com uma taxa declarada e use a mesma taxa fixa em toda a série de movimentos: com taxa mensal, cliente em moeda estrangeira que não mudou de plano aparece como expansão ou contração. Se precisar da visão com câmbio realizado, mostre o efeito cambial numa linha separada. Confira se a coluna convertida vem nula para moeda estrangeira antes de somar.