O faturamento baseado em assentos cobra dos clientes com base no número de usuários em suas contas. O Dodo Payments implementa isso usando o sistema de add-ons: um produto de assinatura base mais um add-on por assento cuja quantidade representa a contagem de assentos.
Implementation Tutorial
Guia passo a passo com exemplos de código.
Add-ons Documentation
Saiba mais sobre o sistema de complementos que alimenta a cobrança baseada em assentos.
Subscription Management
Gerencie assinaturas baseadas em assentos e mudanças de plano.
Webhooks
Acompanhe alterações de assentos com webhooks de assinatura.
O que é Cobrança Baseada em Assentos?
A cobrança baseada em assentos cobra dos clientes de acordo com o número de usuários que acessam seu produto. Em vez de uma tarifa fixa, o preço aumenta conforme o tamanho da equipe.Casos de Uso Comuns
Benefícios da Cobrança Baseada em Assentos
Para sua empresa:- A receita aumenta à medida que os clientes crescem
- Os clientes podem prever os custos com mais facilidade
- Caminho claro de upgrade de individual para equipe e depois para enterprise
- Maior valor ao longo da vida do cliente à medida que as equipes crescem
- Pagam apenas pelos usuários que possuem
- Custos fáceis de entender e prever
- Podem adicionar ou remover usuários conforme necessário
- Preços justos que correspondem ao tamanho da equipe
Como funciona
O Dodo Payments implementa o faturamento baseado em assentos usando o sistema de Add-ons. Uma assinatura baseada em assentos tem duas partes:
O total mensal do cliente é:
Estratégias de Preço
Escolha a estratégia de preço baseada em assentos que se encaixa no seu negócio:Estratégia 1: Base + Add-on por Assento
Inclua um número definido de assentos no plano base, cobrando por assentos adicionais.Estratégia 2: Preço puramente por assento
Cobre uma tarifa fixa por assento, sem taxa base.Estratégia 3: Preço escalonado por assento
Planos base diferentes com tarifas diferentes por assento.Estratégia 4: Pacotes de assentos
Venda assentos em pacotes em vez de individualmente.Configurando o faturamento baseado em assentos
Etapa 1: planeje seus preços
Antes da implementação, defina sua estrutura de preços:1
Define Base Plan
Decida o que está incluído na assinatura base:
- Preço base (pode ser $0 para um modelo puramente por assento)
- Número de assentos incluídos
- Recursos disponíveis neste nível
2
Set Seat Pricing
Determine o custo do add-on por assento:
- Preço por assento adicional
- Quaisquer descontos por volume (por meio de vários add-ons)
- Número máximo de assentos permitido (se aplicável)
3
Consider Billing Frequency
Alinhe o preço dos assentos ao seu ciclo de faturamento:
- Assinaturas mensais → cobranças mensais por assento
- Assinaturas anuais → cobranças anuais por assento (geralmente com desconto)
Etapa 2: crie o add-on por assento
No dashboard do Dodo Payments:- Acesse Products → Add-Ons
- Clique em Create Add-On
- Configure o add-on:
Etapa 3: crie a assinatura base
Crie seu produto de assinatura:- Acesse Products → Create Product
- Selecione Subscription
- Configure os preços e detalhes
- Na seção Add-Ons, associe seu add-on por assento
Etapa 4: associe o add-on ao produto
Vincule o add-on por assento à sua assinatura:- Edite seu produto de assinatura
- Role até a seção Add-Ons
- Clique em Add Add-Ons
- Selecione seu add-on por assento
- Salve as alterações
Agora seu produto de assinatura é compatível com preços baseados em assentos. Os clientes podem comprar qualquer quantidade de assentos adicionais durante o checkout.
Gerenciando assentos
Adicionando assentos a novas assinaturas
Ao criar uma sessão de checkout, especifique a quantidade de assentos:Alterando a quantidade de assentos em assinaturas existentes
Use a Change Plan API para ajustar os assentos. O arrayaddons define a nova quantidade total de assentos (não a diferença).
Removendo assentos
Para reduzir a quantidade de assentos, especifique a quantidade menor:Removendo todos os assentos adicionais
Passe um arrayaddons vazio para remover todos os add-ons:
Proration para alterações de assentos
Quando uma alteração de assentos é aplicada no meio do ciclo, o Dodo Payments calcula a cobrança imediata em três etapas:Como cada modo concede créditos
Com
difference_immediately, o cliente paga apenas a diferença entre o preço do plano antigo e o preço do novo plano. É daí que vem o nome, e é por isso que o valor é o mesmo independentemente de quando no ciclo a alteração é feita.
Se o crédito for maior que a cobrança do novo ciclo, a diferença é mantida como crédito vinculado à assinatura e aplicada automaticamente a renovações futuras.
Exemplo prático: adicionando 5 assentos
Um cenário executado nos quatro modos, para que os números possam ser comparados diretamente.
Nos três modos imediatos, o cliente recebe um mês novo completo por $130 em troca do que paga hoje.
Por que o momento importa para prorated_immediately
A mesma alteração custa mais quanto mais tarde no ciclo for feita, porque resta menos tempo do ciclo atual para ser devolvido como crédito.
O cliente recebe um mês novo completo em todas as linhas. Apenas a divisão entre “já pago” e “pago agora” muda.
Para que uma alteração de assentos custe o mesmo independentemente de quando ocorrer, use
difference_immediately.
Exemplo prático: a “cobrança surpreendente”
Este é o caso que mais costuma surpreender os merchants. Adicionar um pequeno add-on por assento no final do ciclo pode gerar uma cobrança muito maior que o preço do add-on.
Adicionar um assento de $10/mês custa $55.00 com
prorated_immediately. O cliente é cobrado por um mês novo completo de $60 e recebe um crédito de $5 referente ao valor restante do mês antigo, e a data de renovação é redefinida.
Para que pequenas adições no meio do ciclo custem apenas o preço do assento, sem nada além disso, use difference_immediately.
Exemplo prático: removendo assentos (downgrade)
Quando o novo plano custa menos que o crédito, o excedente é mantido como crédito da assinatura e aplicado automaticamente a futuras renovações dessa assinatura. Ele não é adicionado à Customer Wallet nem é um credit entitlement.O crédito cobre a assinatura inteira, incluindo o plano base e todos os add-ons, e não apenas os assentos que estão sendo removidos.
Lendo a resposta de preview
previewChangePlan retorna exatamente os itens de linha que serão cobrados. Cada item de linha tem um proration_factor:
A proration é calculada com precisão de segundos, com base no horário exato da alteração, e não arredondada para o dia mais próximo. Os exemplos práticos acima usam valores arredondados nas transições de dias para facilitar a compreensão.
Faça um preview antes de alterar
Sempre faça um preview da proration antes de realizar alterações:Rastreando assentos com webhooks
Monitore as alterações de assentos ouvindo os webhooks de assinatura:Eventos relevantes
Exemplo de webhook handler
Aplicando limites de assentos
Sua aplicação deve aplicar os limites de assentos. O Dodo Payments acompanha o faturamento, mas você controla o acesso.- Hard Limit
- Soft Limit with Warning
- Auto-Upgrade
Impeça estritamente a adição de usuários além da quantidade de assentos.
Padrões avançados
Diferentes tipos de assento
Ofereça diferentes tipos de assento com preços distintos:Descontos anuais para assentos
Ofereça preços anuais com desconto para os assentos:Requisitos mínimos de assentos
Exija um número mínimo de assentos para determinados planos:Práticas recomendadas
Práticas recomendadas de preços
- Comunicação clara: mostre o preço por assento em destaque na sua página de preços
- Assentos incluídos: considere incluir alguns assentos no preço base para reduzir o atrito
- Descontos por volume: ofereça tarifas menores por assento para equipes maiores e conquiste contratos enterprise
- Incentivos anuais: ofereça descontos nos planos anuais para melhorar o fluxo de caixa e a retenção
Práticas recomendadas técnicas
- Armazene as contagens em cache: armazene localmente as contagens de assentos das assinaturas para evitar chamadas à API em cada solicitação
- Sincronize regularmente: sincronize periodicamente a contagem local de assentos com o Dodo Payments via API
- Trate falhas: se uma alteração de assentos falhar, mostre mensagens de erro claras e opções de nova tentativa
- Trilha de auditoria: registre todas as alterações de assentos para disputas de faturamento e conformidade
Práticas recomendadas de experiência do usuário
- Feedback em tempo real: mostre imediatamente o impacto no custo ao ajustar os assentos
- Etapas de confirmação: exija confirmação antes de alterar a cobrança
- Transparência na cobrança proporcional: explique claramente as cobranças proporcionais antes de aplicá-las
- Downgrades fáceis: não dificulte a redução de assentos (isso gera confiança)
Solução de problemas
Seat count mismatch between app and billing
Seat count mismatch between app and billing
Sintoma: seu app mostra uma contagem de assentos diferente da assinatura.Causas:
- Webhook não recebido ou processado
- Condição de corrida durante a alteração de assentos
- Dados em cache não atualizados
- Implemente handlers de webhook para
subscription.plan_changed - Adicione um botão “Sincronizar com o faturamento” que busque a assinatura atual
- Defina o TTL do cache para garantir atualizações regulares
Unexpected mid-cycle charge amount
Unexpected mid-cycle charge amount
Sintoma: cliente confuso com o valor da cobrança no meio do ciclo.Causa: uso de
prorated_immediately no final do ciclo de faturamento (consulte o exemplo A cobrança surpreendente acima).Soluções:- Sempre use
previewChangePlanantes de fazer alterações - Mostre um detalhamento claro: “Adicionar X assentos custará $Y hoje”
- Mude para
difference_immediatelyse quiser que a cobrança sempre corresponda à diferença de preço
Add-on not appearing in checkout
Add-on not appearing in checkout
Sintoma: o add-on por assento não está disponível durante o checkout.Causas:
- Add-on não associado ao produto
- Add-on arquivado ou excluído
- Incompatibilidade de moeda entre o produto e o add-on
- Verifique se o add-on está associado nas configurações do produto
- Confira o status do add-on no dashboard de Add-Ons
- Garanta que as moedas sejam exatamente iguais
Cannot reduce seats below current usage
Cannot reduce seats below current usage
Sintoma: o cliente quer reduzir os assentos, mas há usuários atribuídos.Soluções:
- Mostre quais usuários precisam ser removidos antes da redução dos assentos
- Implemente um fluxo: remover usuários → reduzir assentos
- Considere um período de tolerância antes de aplicar a redução de assentos
Documentação relacionada
Seat-Based Pricing Tutorial
Guia completo de implementação com código.
Add-ons
Entenda o sistema de add-ons em profundidade.
Plan Changes & Proration
Gerencie modificações de assinaturas.
Subscription Webhooks
Acompanhe eventos de assinatura.