> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Modelos de cobrança híbrida
> Combine vários modos de cobrança para criar estratégias de preços sofisticadas: assinatura + uso, assentos + complementos, base + excedente e muito mais.
A cobrança híbrida combina dois ou mais modelos de cobrança em uma única estratégia de preços. Isso permite capturar valor de diferentes dimensões — taxas recorrentes, uso, assentos e recursos — enquanto oferece flexibilidade e previsibilidade aos clientes.
Base para preços baseados em consumo.
Base para cobrança recorrente.
Amplie as assinaturas com upgrades opcionais.
Modelos de preços por usuário.
***
## O que é cobrança híbrida?
A cobrança híbrida combina várias dimensões de preços em uma única oferta de produto. Em vez de escolher entre assinaturas de preço fixo OU preços baseados em uso, você usa ambos em conjunto.
### Por que usar cobrança híbrida?
| Objetivo comercial | Solução híbrida |
| --------------------------------------------- | ------------------------------------------ |
| Receita previsível + potencial de crescimento | Assinatura base + excedente de uso |
| Preços para equipes que escalam | Por assento + complementos de recursos |
| Conquistar clientes e expandir depois | Taxa base baixa + cobranças por consumo |
| Flexibilidade empresarial | Gasto comprometido + cobranças sob demanda |
| Preços justos para uso variável | Franquia incluída + pagamento por uso |
### Padrões híbridos comuns
| Modelo | Descrição | Exemplo | Suporte nativo |
| -------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------- | ---------------------- |
| **1. Assinatura + Uso** | Taxa base + cobranças por consumo | \$49/mês + \$0.01/chamada de API após 10 mil gratuitas | ✅ Completo |
| **2. Assinatura + Assentos** | Taxa da plataforma + cobranças por usuário | \$99/mês + \$15/assento | ✅ Completo |
| **3. Assinatura + Complementos de recursos** | Plano principal + upgrades opcionais | \$29/mês + \$19/mês de analytics + \$9/mês de acesso à API | ✅ Completo |
| **4. Assentos + Uso** | Taxa por usuário + excedente de consumo | \$10/usuário/mês + \$0.05/GB após 5 GB/usuário | ⚠️ Solução alternativa |
| **5. Assinatura + Assentos + Uso** | Plataforma + usuários + consumo (híbrido triplo) | \$199/mês + \$20/assento + excedente de uso | ⚠️ Solução alternativa |
| **6. Base escalonada + Excedente de uso** | Diferentes níveis com diferentes franquias | Starter (5 mil chamadas) versus Pro (50 mil chamadas) + excedente | ✅ Completo |
| **7. Assinatura + Cobranças sob demanda** | Taxa recorrente + cobranças manuais variáveis | Retainer de \$99/mês + cobrança por hora de trabalho | ✅ Completo |
***
## Modelo híbrido 1: Assinatura + Uso
O modelo híbrido mais comum. Os clientes pagam uma taxa de assinatura base mais cobranças pelo consumo que exceder as franquias incluídas.
### Como funciona
**Plano Pro: \$49/mês**
* **Incluído**: 10.000 chamadas de API/mês
* **Excedente**: \$0.005 por chamada após 10.000
**Cálculo de exemplo** (o cliente usa 25.000 chamadas este mês):
* Assinatura base: \$49.00
* Excedente: (25.000 - 10.000) × $0.005 = $75.00
* **Total: \$124.00**
### Casos de uso
* **Plataformas de API**: Acesso base + cobranças por solicitação
* **Serviços de AI/ML**: Assinatura + uso de tokens/gerações
* **Serviços de armazenamento**: Plano base + excedente por GB
* **Plataformas de comunicação**: Base + cobranças por mensagem/minuto
### Implementação
Configure um medidor para acompanhar a dimensão de uso faturável.
```bash theme={null}
Dashboard: Meters → Create Meter
Event Name: "api.call"
Aggregation: Count
This tracks API calls per customer
```
Crie um produto de assinatura e associe o medidor de uso com os preços.
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Pro Plan"
Base Price: $49/month
Then attach usage pricing:
- Meter: api.call
- Price per unit: $0.005
- Free threshold: 10,000 (included in subscription)
```
O medidor de uso é associado diretamente ao produto de assinatura. As cobranças de uso são calculadas e adicionadas automaticamente à fatura da assinatura.
Crie uma sessão de checkout com seu produto de assinatura.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{ product_id: 'prod_pro_plan', quantity: 1 }
],
customer: { email: 'customer@example.com' },
return_url: 'https://yourapp.com/success'
});
```
Acompanhe o uso durante todo o período de cobrança.
```typescript theme={null}
await fetch('https://test.dodopayments.com/events/ingest', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
events: [{
event_id: `call_${Date.now()}`,
customer_id: 'cus_123',
event_name: 'api.call',
timestamp: new Date().toISOString(),
metadata: { endpoint: '/v1/generate' }
}]
})
});
```
### Variações de preços
O limite gratuito cobre o uso incluído na assinatura base.
**Plano Pro: \$49/mês**
* Inclui: 10.000 chamadas de API
* Excedente: \$0.005/chamada após 10.000
* O cliente usa 8.000 → Paga \$49 (sem excedente)
Sem taxa base; cada unidade é faturável desde o primeiro uso.
**Pay-As-You-Go: base de \$0/mês**
* Inclui: 0 chamadas de API
* Uso: \$0.01/chamada desde a primeira chamada
* O cliente usa 5.000 → Paga \$50
Diferentes níveis incluem diferentes franquias.
* **Starter**: \$19/mês (1.000 chamadas incluídas)
* **Pro**: \$49/mês (10.000 chamadas incluídas)
* **Enterprise**: \$199/mês (100.000 chamadas incluídas)
* Todos os níveis: excedente de \$0.005/chamada
***
## Modelo híbrido 2: Assinatura + Assentos
Taxa da plataforma mais cobranças por usuário. Ideal para ferramentas de colaboração em equipe e SaaS B2B.
### Como funciona
**Plano Team: $99/mês + $15/assento**
* **Taxa base da plataforma**: \$99/mês (inclui 3 assentos)
* **Assentos adicionais**: \$15/assento/mês
**Cálculo de exemplo** (equipe de 12 usuários):
* Taxa da plataforma: \$99.00
* Assentos adicionais: (12 - 3) × $15 = $135.00
* **Total: \$234.00/mês**
### Casos de uso
* **Ferramentas de colaboração**: Taxa do workspace + por membro
* **Sistemas de CRM**: Licença da plataforma + por representante de vendas
* **Gerenciamento de projetos**: Plano da equipe + por colaborador
* **Ferramentas para desenvolvedores**: Taxa da organização + por desenvolvedor
### Implementação
Crie um complemento para assentos adicionais.
```bash theme={null}
Dashboard: Products → Add-ons → Create Add-on
Name: "Additional Seat"
Price: $15/month
Description: "Add another team member"
```
Crie o produto de assinatura com a taxa da plataforma e associe o complemento.
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Team Plan"
Price: $99/month
Description: "Includes 3 team members"
Then in Add-ons section:
- Attach: "Additional Seat" add-on
```
Especifique a quantidade de assentos durante o checkout.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [{
product_id: 'prod_team_plan',
quantity: 1,
addons: [{
addon_id: 'addon_seat',
quantity: 9 // 9 extra seats (12 total with 3 included)
}]
}],
customer: { email: 'admin@company.com' },
return_url: 'https://yourapp.com/success'
});
```
Adicione ou remova assentos em assinaturas existentes.
```typescript theme={null}
// Add 5 more seats
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_team_plan',
quantity: 1,
proration_billing_mode: 'prorated_immediately',
addons: [{
addon_id: 'addon_seat',
quantity: 14 // New total: 14 extra seats
}]
});
```
### Variações de preços
O plano base inclui alguns assentos; cobre os adicionais.
**Plano Team: \$99/mês**
* Inclui: 5 assentos
* Assentos adicionais: \$15/assento/mês
* 20 usuários = \$99 + (15 × \$15) = \$324/mês
Sem taxa da plataforma, apenas cobranças por usuário.
**Por usuário: \$25/usuário/mês**
* Sem taxa da plataforma
* 5 usuários = \$125/mês
* 50 usuários = \$1,250/mês
Implementação: defina o preço da assinatura base como \$0 e use apenas o complemento de assentos.
O preço por assento diminui nos níveis mais altos.
* **Starter**: \$20/assento (1–10 assentos)
* **Growth**: \$15/assento (11–50 assentos)
* **Enterprise**: \$10/assento (51+ assentos)
Implementação: crie produtos de assinatura separados para cada nível, com preços diferentes para os complementos.
***
## Modelo híbrido 3: Assinatura + Complementos de recursos
Assinatura principal com upgrades opcionais de recursos que os clientes podem adicionar.
### Como funciona
**Plano Core: \$29/mês**
**Complementos opcionais:**
* Analytics avançado: +\$19/mês
* Acesso à API: +\$9/mês
* Suporte prioritário: +\$29/mês
* White-label: +\$49/mês
**Cálculo de exemplo** (o cliente escolhe Core + Analytics + acesso à API):
* Plano Core: \$29.00
* Analytics: \$19.00
* Acesso à API: \$9.00
* **Total: \$57.00/mês**
### Casos de uso
* **Plataformas SaaS**: Recursos principais + módulos premium
* **Ferramentas de marketing**: Ferramenta base + integrações
* **Produtos de analytics**: Dashboard + relatórios avançados
* **Software de segurança**: Proteção básica + recursos avançados
### Implementação
Crie um complemento para cada recurso opcional.
```bash theme={null}
# Add-on 1: Advanced Analytics
Dashboard: Products → Add-ons → Create Add-on
Name: "Advanced Analytics"
Price: $19/month
# Add-on 2: API Access
Name: "API Access"
Price: $9/month
# Add-on 3: Priority Support
Name: "Priority Support"
Price: $29/month
# Add-on 4: White-label
Name: "White-label"
Price: $49/month
```
Defina sua assinatura base e associe todos os complementos de recursos.
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Core Plan"
Price: $29/month
Then in Add-ons section:
- Attach all feature add-ons
```
Faça o checkout com os recursos selecionados.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [{
product_id: 'prod_core_plan',
quantity: 1,
addons: [
{ addon_id: 'addon_analytics', quantity: 1 },
{ addon_id: 'addon_api_access', quantity: 1 }
// Customer didn't select support or white-label
]
}],
return_url: 'https://yourapp.com/success'
});
```
Os clientes podem adicionar recursos a assinaturas existentes.
```typescript theme={null}
// Customer wants to add Priority Support
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_core_plan',
quantity: 1,
proration_billing_mode: 'prorated_immediately',
addons: [
{ addon_id: 'addon_analytics', quantity: 1 },
{ addon_id: 'addon_api_access', quantity: 1 },
{ addon_id: 'addon_priority_support', quantity: 1 } // New!
]
});
```
***
## Modelo híbrido 4: Assentos + Uso
Taxa por usuário combinada com cobranças baseadas em consumo. Cada usuário recebe uma franquia.
**Limitação**: Dodo Payments atualmente não oferece suporte à associação de medidores de uso e complementos ao mesmo produto de assinatura. Este modelo exige uma solução alternativa usando lógica no nível da aplicação.
**Em breve**: o suporte nativo à cobrança híbrida de Assentos + Uso está no nosso roadmap. Isso permitirá associar medidores de uso e complementos de assentos ao mesmo produto de assinatura.
### Como funciona
**Analytics para equipes: \$20/usuário/mês**
**Cada usuário inclui:**
* 5 GB de processamento de dados/mês
* Excedente: \$2/GB após a franquia
**Cálculo de exemplo** (equipe de 10 usuários usando 80 GB no total):
* Taxas dos assentos: 10 × $20 = $200.00
* Dados incluídos: 10 × 5 GB = 50 GB
* Excedente: (80 - 50) × $2 = $60.00
* **Total: \$260.00/mês**
### Casos de uso
* **Plataformas de analytics**: Por analista + processamento de dados
* **Ferramentas de design**: Por designer + armazenamento/exportações
* **Ambientes de desenvolvimento**: Por desenvolvedor + horas de computação
* **Ferramentas de comunicação**: Por usuário + volume de mensagens/chamadas
### Opções de implementação
Como não é possível associar medidores de uso e complementos à mesma assinatura, escolha uma destas abordagens:
Use uma assinatura baseada em uso e gerencie a cobrança de assentos na sua aplicação.
```bash theme={null}
Dashboard: Meters → Create Meter
Event Name: "data.processed"
Aggregation: Sum
Property: "bytes"
```
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Team Analytics"
Base Price: $0/month
Attach usage pricing:
- Meter: data.processed
- Price per unit: $2/GB
- Free threshold: 0 (managed by your app)
```
Acompanhe a quantidade de assentos e calcule as taxas dos assentos separadamente.
```typescript theme={null}
// Your application tracks seats and calculates total cost
async function calculateMonthlyBill(customerId: string) {
const seatCount = await getSeatCount(customerId);
const seatFee = seatCount * 20; // $20/seat
// Usage is billed by Dodo automatically
// You invoice/charge seat fees separately or include in base price
// Alternatively, adjust base subscription price when seats change
const totalBasePrice = seatCount * 2000; // $20/seat in cents
await client.subscriptions.update('sub_123', {
// Update subscription to reflect seat-based pricing
});
}
```
Ajuste o uso incluído com base na quantidade de assentos.
```typescript theme={null}
// When checking usage, apply per-seat allowance
async function checkUsageOverage(customerId: string) {
const seatCount = await getSeatCount(customerId);
const includedGB = seatCount * 5; // 5 GB per user
const currentUsage = await getUsageFromDodo(customerId);
const overage = Math.max(0, currentUsage - includedGB);
// Overage is billed by Dodo at $2/GB
return { included: includedGB, used: currentUsage, overage };
}
```
Use complementos para os assentos e cobre o uso manualmente por meio de cobranças sob demanda.
```bash theme={null}
Dashboard: Products → Add-ons → Create Add-on
Name: "Team Member"
Price: $20/month
```
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Team Analytics"
Base Price: $0/month
Attach add-on:
- "Team Member" add-on
Enable on-demand charging
```
```typescript theme={null}
// Track usage events in your system
async function trackDataProcessed(customerId: string, bytes: number) {
await saveUsageEvent({
customer_id: customerId,
event_type: 'data.processed',
bytes: bytes,
timestamp: new Date()
});
}
```
Calcule e cobre manualmente os excedentes de uso.
```typescript theme={null}
async function billUsageOverage(subscriptionId: string) {
const subscription = await getSubscription(subscriptionId);
const seatCount = subscription.addons.find(a => a.id === 'addon_seat')?.quantity || 0;
const includedGB = seatCount * 5;
const usedGB = await calculatePeriodUsage(subscription.customer_id);
const overageGB = Math.max(0, usedGB - includedGB);
if (overageGB > 0) {
const overageCharge = overageGB * 200; // $2/GB in cents
await client.subscriptions.charge(subscriptionId, {
product_price: overageCharge,
product_description: `Data overage: ${overageGB} GB × $2/GB`
});
}
}
```
**Recomendação**: a Opção B (complemento de assentos + uso sob demanda) costuma ser mais fácil de implementar porque Dodo gerencia a cobrança de assentos automaticamente. Você só precisa acompanhar e cobrar os excedentes de uso.
***
## Modelo híbrido 5: Assinatura + Assentos + Uso (híbrido triplo)
O modelo mais completo: taxa da plataforma + por usuário + consumo.
**Limitação**: Dodo Payments atualmente não oferece suporte à associação de medidores de uso e complementos ao mesmo produto de assinatura. Este modelo exige uma solução alternativa.
**Em breve**: o suporte nativo à cobrança híbrida tripla (Base + Assentos + Uso) está no nosso roadmap. Isso permitirá associar medidores de uso e complementos de assentos ao mesmo produto de assinatura.
### Como funciona
**Plataforma Enterprise**
* **Taxa da plataforma**: \$199/mês
* **Por assento**: \$25/usuário/mês
* **Uso**: \$0.10/1.000 chamadas de API (50 mil incluídas)
**Cálculo de exemplo** (empresa com 20 usuários e 150.000 chamadas de API):
* Plataforma: \$199.00
* Assentos: 20 × $25 = $500.00
* Uso: (150 mil - 50 mil) × \$0.10/1 mil = \$10.00
* **Total: \$709.00/mês**
### Casos de uso
* **SaaS Enterprise**: Plataforma + equipe + consumo
* **Plataformas de dados**: Workspace + analistas + consultas
* **Plataformas de integração**: Hub + conectores + transações
* **Plataformas de AI**: Workspace + desenvolvedores + inferência
### Opções de implementação
Escolha uma destas abordagens para implementar a cobrança híbrida tripla:
Use uma assinatura com complementos de assentos e cobre o uso manualmente por meio de cobranças sob demanda.
**Esta é a abordagem recomendada** porque Dodo gerencia automaticamente a taxa da plataforma e a cobrança de assentos.
```bash theme={null}
Dashboard: Products → Add-ons → Create Add-on
Name: "User Seat"
Price: $25/month
```
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Enterprise Platform"
Base Price: $199/month
Attach add-on:
- "User Seat" add-on
Enable on-demand charging
```
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [{
product_id: 'prod_enterprise_platform',
quantity: 1,
addons: [{
addon_id: 'addon_user_seat',
quantity: 20 // 20 users
}]
}],
customer: { email: 'enterprise@company.com' },
return_url: 'https://yourapp.com/success'
});
```
Armazene os eventos de uso no seu sistema.
```typescript theme={null}
// Track API calls in your system
async function trackApiCall(customerId: string, endpoint: string) {
await saveUsageEvent({
customer_id: customerId,
event_type: 'api.call',
endpoint: endpoint,
timestamp: new Date()
});
}
```
Calcule e cobre os excedentes de uso por meio de uma cobrança sob demanda.
```typescript theme={null}
async function billUsageOverage(subscriptionId: string) {
const usage = await calculatePeriodUsage(subscriptionId);
const includedCalls = 50000;
const overageCalls = Math.max(0, usage.totalCalls - includedCalls);
if (overageCalls > 0) {
// $0.10 per 1000 calls = $0.0001 per call
const overageCharge = Math.ceil(overageCalls / 1000) * 10; // cents
await client.subscriptions.charge(subscriptionId, {
product_price: overageCharge,
product_description: `API usage: ${overageCalls.toLocaleString()} calls over 50K included`
});
}
}
```
Use uma assinatura com medidor de uso e gerencie a cobrança de assentos na sua aplicação.
```bash theme={null}
Dashboard: Meters → Create Meter
Event Name: "api.call"
Aggregation: Count
```
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Enterprise Platform"
Base Price: $199/month
Attach usage pricing:
- Meter: api.call
- Price: $0.10 per 1000 calls
- Free threshold: 50,000
```
Acompanhe a quantidade de assentos e ajuste o preço da assinatura base de acordo.
```typescript theme={null}
// When seats change, update subscription price
async function updateSeatCount(subscriptionId: string, newSeatCount: number) {
const basePlatformFee = 19900; // $199 in cents
const perSeatFee = 2500; // $25 in cents
const totalPrice = basePlatformFee + (newSeatCount * perSeatFee);
// Store seat count in your system
await updateSeatsInDatabase(subscriptionId, newSeatCount);
// Note: You may need to handle this via plan changes or
// create multiple tier products for common seat counts
}
```
```typescript theme={null}
await fetch('https://test.dodopayments.com/events/ingest', {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
events: [{
event_id: `api_${Date.now()}`,
customer_id: 'cus_enterprise',
event_name: 'api.call',
timestamp: new Date().toISOString()
}]
})
});
```
**Recomendação**: a Opção A (Base + Assentos + Uso sob demanda) geralmente é mais fácil porque Dodo gerencia automaticamente a cobrança da plataforma e dos assentos. Você só precisa acompanhar o uso e enviar as cobranças ao final de cada ciclo de cobrança.
***
## Modelo híbrido 6: Base escalonada + Excedente de uso
Diferentes níveis de assinatura com diferentes franquias incluídas e taxas de excedente.
### Como funciona
| Nível | Preço | Chamadas incluídas | Taxa de excedente |
| -------------- | --------- | ------------------ | ----------------- |
| **Starter** | \$19/mês | 1.000 | \$0.02/chamada |
| **Pro** | \$79/mês | 25.000 | \$0.01/chamada |
| **Business** | \$199/mês | 100.000 | \$0.005/chamada |
| **Enterprise** | \$499/mês | 500.000 | \$0.002/chamada |
### Implementação
Crie produtos de assinatura separados para cada nível, cada um com sua própria configuração de uso:
```bash theme={null}
# For each tier, create a subscription product:
# Starter Tier
Dashboard: Create Product → Subscription
Name: "Starter"
Base Price: $19/month
Usage Pricing:
- Meter: api.call
- Price: $0.02/call
- Free threshold: 1,000
# Pro Tier
Name: "Pro"
Base Price: $79/month
Usage Pricing:
- Meter: api.call
- Price: $0.01/call
- Free threshold: 25,000
# ... and so on for Business and Enterprise
```
### Caminho de upgrade
Quando os clientes fazem upgrade de nível, eles recebem:
* Maior franquia incluída
* Taxas de excedente menores
* Mais valor por dólar
```typescript theme={null}
// Customer upgrades from Starter to Pro
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_pro',
quantity: 1,
proration_billing_mode: 'prorated_immediately'
});
```
***
## Modelo híbrido 7: Assinatura + Cobranças sob demanda
Assinatura recorrente mais cobranças manuais variáveis por serviços ou excedentes.
### Como funciona
**Plano Retainer: \$199/mês**
**Inclui:**
* Acesso à plataforma
* 5 horas de consultoria/mês
* Suporte por e-mail
**Cobranças sob demanda (conforme necessário):**
* Consultoria adicional: \$150/hora
* Desenvolvimento personalizado: \$200/hora
* Suporte emergencial: \$100/incidente
**Cálculo de exemplo** (este mês):
* Retainer: \$199.00
* 3 horas adicionais de consultoria: \$450.00
* 1 suporte emergencial: \$100.00
* **Total: \$749.00**
### Casos de uso
* **Serviços de consultoria**: Retainer + cobrança por hora
* **Serviços gerenciados**: Taxa base + cobranças por incidente
* **Serviços de agência**: Taxa mensal + cobranças por projeto
* **Planos de suporte**: Taxa de SLA + por ticket ou hora
### Implementação
Configure a assinatura com a cobrança sob demanda habilitada.
```typescript theme={null}
const subscription = await client.subscriptions.create({
billing: {
city: 'San Francisco',
country: 'US',
state: 'CA',
street: '123 Main St',
zipcode: '94105'
},
customer: { customer_id: 'cus_123' },
product_id: 'prod_retainer',
quantity: 1,
payment_link: true,
return_url: 'https://yourapp.com/success',
on_demand: {
mandate_only: false,
product_price: 19900 // $199 initial charge
}
});
```
Crie cobranças quando os serviços forem entregues.
```typescript theme={null}
// Charge for 3 hours of consulting
await client.subscriptions.charge('sub_123', {
product_price: 45000, // $450.00 (3 × $150)
product_description: 'Consulting - 3 hours (March 15)'
});
// Charge for emergency support incident
await client.subscriptions.charge('sub_123', {
product_price: 10000, // $100.00
product_description: 'Emergency support - Server outage (March 18)'
});
```
Todas as cobranças aparecem na fatura do cliente.
```typescript theme={null}
// Retrieve subscription charges
const payments = await client.payments.list({
subscription_id: 'sub_123'
});
// Show itemized breakdown to customer
payments.items.forEach(payment => {
console.log(`${payment.description}: $${payment.amount / 100}`);
});
```
***
## Exemplos do mundo real
Estes exemplos mostram estruturas de preços ideais. Devido à limitação de que medidores de uso e complementos não podem ser associados ao mesmo produto, algumas combinações exigem soluções alternativas (usando cobranças sob demanda para uso ou assentos gerenciados pela aplicação).
### Exemplo 1: Plataforma SaaS de AI
**Estrutura de preços:**
* **Assinatura base**: \$99/mês (acesso à plataforma, 5 assentos incluídos)
* **Complemento de assentos**: \$20/assento/mês
* **Complementos de recursos**: Modelos personalizados (\$49/mês), acesso à API (\$29/mês), fila prioritária (\$19/mês)
* **Excedente de uso**: \$0.02 por 1.000 tokens após 100 mil (cobrado sob demanda)
**Implementação**: use uma assinatura com complementos de assentos e recursos. Acompanhe o uso de tokens na sua aplicação e cobre os excedentes por meio de cobranças sob demanda ao final do ciclo de cobrança.
**Cliente de exemplo** (12 usuários, 500 mil tokens, Modelos personalizados + acesso à API):
| Componente | Cálculo | Valor |
| ---------------------- | ------------------------------------ | ------------- |
| Base | Taxa da plataforma | \$99 |
| Assentos adicionais | 7 × \$20 | \$140 |
| Modelos personalizados | Complemento | \$49 |
| Acesso à API | Complemento | \$29 |
| Excedente de tokens | 400 mil × \$0.02/1 mil (sob demanda) | \$8 |
| **Total** | | **\$325/mês** |
### Exemplo 2: Plataforma de ferramentas para desenvolvedores
**Opções de níveis:**
| | Gratuito | Pro | Enterprise |
| ----------------- | -------- | ----------- | ---------- |
| **Preço** | \$0/mês | \$29/mês | \$199/mês |
| **Usuários** | 1 | 5 incluídos | Ilimitados |
| **Builds** | 100 | 1.000 | 10.000 |
| **Armazenamento** | 1 GB | 10 GB | 100 GB |
**Opções de implementação:**
**Opção A** (focada em uso): crie produtos com medidores de uso para builds/armazenamento. Gerencie os usuários na sua aplicação.
**Opção B** (focada em assentos): crie produtos com complementos de assentos. Acompanhe o uso de builds/armazenamento e cobre os excedentes por meio de cobranças sob demanda.
**Complementos (se usar a Opção B):**
* Usuários adicionais: \$10/usuário/mês
* Builds prioritários: \$19/mês
* Domínios personalizados: \$9/domínio/mês
### Exemplo 3: Automação de marketing
**Estrutura de preços:**
* **Base**: \$79/mês (recursos principais de automação, 3 assentos incluídos)
* **Níveis de contatos** (complementos): 1 mil incluídos, 5 mil (+\$30), 25 mil (+\$80), 100 mil (+\$200)
* **Complementos de recursos**: Marketing por SMS (\$29/mês), Landing Pages (\$19/mês), Testes A/B (\$29/mês)
* **Assentos da equipe**: complemento de \$15/usuário/mês
* **Volume de e-mails**: acompanhe na aplicação e cobre o excedente sob demanda (\$1/1.000 e-mails acima do limite)
**Implementação**: use uma assinatura com complementos de nível de contatos, recursos e assentos. Acompanhe os envios de e-mail na sua aplicação e cobre os excedentes por meio de cobranças sob demanda.
***
## Práticas recomendadas de implementação
### Clareza na página de preços
Facilite a compreensão dos preços híbridos. Mostre de forma destacada na página de preços os custos base, o que está incluído e como funcionam os excedentes.
**Bom**: "\$49/mês inclui 10.000 chamadas de API. Chamadas adicionais: \$0.005 cada"
**Ruim**: "\$49/mês + taxas de uso"
### Previsibilidade de custos
Ajude os clientes a estimar seus custos:
```typescript theme={null}
// Provide a cost calculator
function estimateMonthlyCost({
plan,
seats,
expectedUsage,
addons
}: EstimateParams): number {
let total = plan.basePrice;
// Add seat costs
const extraSeats = Math.max(0, seats - plan.includedSeats);
total += extraSeats * plan.seatPrice;
// Add usage overage
const overage = Math.max(0, expectedUsage - plan.includedUsage);
total += overage * plan.overageRate;
// Add feature add-ons
total += addons.reduce((sum, addon) => sum + addon.price, 0);
return total;
}
```
### Visibilidade do uso
Mostre aos clientes o uso deles em tempo real:
```typescript theme={null}
// Display usage dashboard
async function getUsageSummary(subscriptionId: string) {
const usage = await client.subscriptions.retrieveUsageHistory(subscriptionId);
// Each item is a billing period; each meter reports its usage for that period.
const latestPeriod = usage.items[0];
return latestPeriod.meters.map((meter) => {
const consumed = Number(meter.consumed_units);
const chargeable = Number(meter.chargeable_units);
return {
meter: meter.name,
current: consumed,
included: meter.free_threshold,
remaining: Math.max(0, meter.free_threshold - consumed),
overage: chargeable,
cost: meter.total_price
};
});
}
```
### Transparência da cobrança
Forneça faturas detalhadas mostrando todos os componentes:
| Item | Valor |
| -------------------------------------------------- | ------------ |
| Plano Pro (mensal) | \$49.00 |
| Assentos adicionais (7 × \$15.00) | \$105.00 |
| Uso da API — incluído (10.000 chamadas) | \$0.00 |
| Uso da API — excedente (15.420 chamadas × \$0.005) | \$77.10 |
| Complemento de Analytics avançado | \$19.00 |
| **Subtotal** | **\$250.10** |
| Imposto (8.5%) | \$21.26 |
| **Total devido** | **\$271.36** |
***
## Solução de problemas de cobrança híbrida
**Sintomas**: o uso mostra 0 ou valores incorretos.
**Soluções**:
1. Verifique se a ingestão de eventos está funcionando (confira as respostas da API)
2. Confirme se `customer_id` corresponde ao cliente da assinatura
3. Verifique se `event_name` corresponde à configuração do medidor
4. Verifique se os eventos têm timestamps corretos (não definidos para o futuro)
**Sintomas**: o cliente é cobrado com valores inesperados ao alterar os planos.
**Soluções**:
1. Use a API `previewChangePlan` para mostrar as cobranças exatas antes da confirmação
2. Comunique que o rateio proporcional se aplica à assinatura E aos complementos
3. Considere usar `difference_immediately` para simplificar a cobrança de upgrades
**Sintomas**: o cliente é cobrado por um uso que deveria ser gratuito.
**Soluções**:
1. Verifique se o limite gratuito está configurado no produto baseado em uso
2. Confira se a unidade do limite corresponde à agregação de eventos (chamadas versus solicitações)
3. Confirme se o medidor de uso está corretamente associado ao produto de assinatura
**Sintomas**: não é possível adicionar assentos ou recursos durante o checkout.
**Soluções**:
1. Verifique se os complementos estão associados ao produto de assinatura no dashboard
2. Confira se os IDs dos complementos estão corretos nas chamadas da API
3. Certifique-se de que a moeda do complemento corresponde à moeda do produto de assinatura
***
## Documentação relacionada
Visão geral de todos os tipos de produtos e guias.
Implementação completa da cobrança por uso.
Gerenciamento de assinaturas recorrentes.
Ampliação de assinaturas com complementos.