Skip to main content
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
Para seus clientes:
  • 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 é:
Exemplo: 8 assentos adicionais em um Team Plan

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.
Ideal para: produtos em que equipes pequenas conseguem trabalhar com a oferta base.

Estratégia 2: Preço puramente por assento

Cobre uma tarifa fixa por assento, sem taxa base.
Implementação: defina o preço do plano base como $0 e use apenas o add-on de assento. Ideal para: preços simples e transparentes.

Estratégia 3: Preço escalonado por assento

Planos base diferentes com tarifas diferentes por assento.
Implementação: crie produtos separados para cada nível, com preços diferentes para os add-ons. Ideal para: incentivar upgrades para níveis superiores; vendas enterprise.

Estratégia 4: Pacotes de assentos

Venda assentos em pacotes em vez de individualmente.
Implementação: crie vários add-ons para diferentes tamanhos de pacote. Ideal para: simplificar as decisões de compra; incentivar compromissos maiores.

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:
  1. Acesse Products → Add-Ons
  2. Clique em Create Add-On
  3. Configure o add-on:
Use nomes descritivos para os add-ons que façam sentido nas faturas. “Additional Team Seat” é mais claro do que “Seat Add-on” para clientes que estão conferindo suas cobranças.

Etapa 3: crie a assinatura base

Crie seu produto de assinatura:
  1. Acesse Products → Create Product
  2. Selecione Subscription
  3. Configure os preços e detalhes
  4. 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:
  1. Edite seu produto de assinatura
  2. Role até a seção Add-Ons
  3. Clique em Add Add-Ons
  4. Selecione seu add-on por assento
  5. 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 array addons 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 array addons 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:
O valor do crédito depende do modo de proration escolhido. A cobrança é sempre de um ciclo completo.
A cobrança é sempre referente a um ciclo completo. Apenas o crédito varia de acordo com o modo. É por isso que o valor cobrado raramente é “novos assentos × preço × dias restantes”.Com prorated_immediately, o crédito diminui à medida que o ciclo avança, então a mesma alteração de assentos custa mais quanto mais tarde for feita. Com difference_immediately e full_immediately, o crédito não depende do momento da alteração, então os dois custam o mesmo em qualquer dia do ciclo.

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.
prorated_immediately, difference_immediately e full_immediately reiniciam o ciclo de cobrança na data da alteração. A próxima renovação é reancorada no dia em que a alteração de assentos é aplicada. Apenas do_not_bill mantém a data de renovação original (a nova quantidade de assentos é cobrada integralmente na próxima renovação, sem cobrança no momento da alteração).
do_not_bill aplica a alteração de assentos imediatamente, não na renovação. A nova quantidade de assentos entra em vigor assim que a chamada é concluída, mas nada é cobrado até a próxima renovação.Ao adicionar assentos, o cliente os utiliza gratuitamente pelo restante do ciclo atual. Adicionar 5 assentos a $10 no dia 1 de um ciclo de 30 dias dá ao cliente 5 assentos gratuitos por 29 dias, e o valor maior é cobrado pela primeira vez na data de renovação original.Ao remover assentos, o inverso se aplica: os assentos são removidos imediatamente e nenhum crédito é concedido pelo período do ciclo que já foi pago.Use do_not_bill quando esse for o comportamento desejado, como em um upgrade de cortesia ou em um período de teste de assentos extras acordado com o cliente.

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:
Interpretando isso: $50 do plano base e 3 × $10 de add-on creditados a 50%, um plano base completo de $50 cobrado e 8 × $10 de add-on cobrados. Crédito = $40, cobrança = $130, líquido = $90.
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.
Escolhendo um modo de proration para alterações de assentos
  • difference_immediately — o cliente paga a diferença de preço, independentemente de quando a alteração é feita. É o modo mais previsível para equipes que ajustam assentos com frequência e o mais fácil de explicar na sua UI.
  • prorated_immediately — o cliente recebe crédito apenas pelo tempo restante do ciclo atual. O custo aumenta quanto mais tarde no ciclo a alteração é feita.
  • full_immediately — o cliente paga por um ciclo novo completo, sem crédito pelo tempo não utilizado.
  • do_not_bill — a alteração de assentos entra em vigor imediatamente, mas nada é cobrado agora. Os assentos adicionados são gratuitos até a próxima renovação; os assentos removidos são retirados sem crédito. A data de renovação é preservada e a nova quantidade de assentos é cobrada integralmente a partir dessa renovação. É o único modo que não reinicia o ciclo de cobrança.
Os assentos concedidos por meio de do_not_bill não recebem crédito em uma alteração posterior de plano, pois nunca foram cobrados. Se você adicionar 5 assentos com do_not_bill e depois alterar para 3 assentos, o cliente será cobrado integralmente por 3 assentos, sem crédito pelos 5 que tinha disponíveis.
Sempre chame previewChangePlan e mostre o valor retornado antes de confirmar. Consulte o Guia de Proration para comparações detalhadas.

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

O array addons no payload do webhook contém as quantidades atuais dos add-ons. Some-as para obter a contagem total de assentos. Se o seu plano base incluir assentos (por exemplo, 5 incluídos), adicione essa quantidade ao total de add-ons na lógica da sua aplicação.

Aplicando limites de assentos

Sua aplicação deve aplicar os limites de assentos. O Dodo Payments acompanha o faturamento, mas você controla o acesso.
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:
Implementação: crie add-ons separados para cada tipo de assento.

Descontos anuais para assentos

Ofereça preços anuais com desconto para os assentos:
Implementação: crie produtos separados para planos mensais e anuais, com preços diferentes para os add-ons.

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

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
Soluções:
  1. Implemente handlers de webhook para subscription.plan_changed
  2. Adicione um botão “Sincronizar com o faturamento” que busque a assinatura atual
  3. Defina o TTL do cache para garantir atualizações regulares
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:
  1. Sempre use previewChangePlan antes de fazer alterações
  2. Mostre um detalhamento claro: “Adicionar X assentos custará $Y hoje”
  3. Mude para difference_immediately se quiser que a cobrança sempre corresponda à diferença de preço
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
Soluções:
  1. Verifique se o add-on está associado nas configurações do produto
  2. Confira o status do add-on no dashboard de Add-Ons
  3. Garanta que as moedas sejam exatamente iguais
Sintoma: o cliente quer reduzir os assentos, mas há usuários atribuídos.Soluções:
  1. Mostre quais usuários precisam ser removidos antes da redução dos assentos
  2. Implemente um fluxo: remover usuários → reduzir assentos
  3. 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.
Última modificação em 26 de setembro de 2026