> ## 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 facturación híbrida
> Combina varios modos de facturación para crear estrategias de precios sofisticadas: suscripción + uso, usuarios + complementos, base + excedente y mucho más.
La facturación híbrida combina dos o más modelos de facturación en una única estrategia de precios. Esto te permite capturar valor de diferentes dimensiones —tarifas recurrentes, uso, usuarios y funcionalidades— y, al mismo tiempo, ofrecer flexibilidad y previsibilidad a los clientes.
Base para precios basados en el consumo.
Base para la facturación recurrente.
Amplía las suscripciones con mejoras opcionales.
Modelos de precios por usuario.
***
## ¿Qué es la facturación híbrida?
La facturación híbrida combina varias dimensiones de precios en una única oferta de producto. En lugar de elegir entre suscripciones de tarifa fija O precios basados en el uso, utilizas ambos modelos conjuntamente.
### ¿Por qué usar la facturación híbrida?
| Objetivo empresarial | Solución híbrida |
| ----------------------------------------------- | ---------------------------------------------------- |
| Ingresos previsibles + potencial de crecimiento | Suscripción base + excedente por uso |
| Precios para equipos que escalan | Precio por usuario + complementos de funcionalidades |
| Captar clientes y ampliar después | Tarifa base baja + cargos por consumo |
| Flexibilidad empresarial | Gasto comprometido + cargos bajo demanda |
| Precios justos para uso variable | Asignación incluida + pago por uso |
### Patrones híbridos comunes
| Modelo | Descripción | Ejemplo | Compatibilidad nativa |
| ---------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------- | ----------------------- |
| **1. Suscripción + uso** | Tarifa base + cargos por consumo | \$49/mes + \$0.01/llamada a la API después de 10K gratuitas | ✅ Completa |
| **2. Suscripción + usuarios** | Tarifa de plataforma + cargos por usuario | \$99/mes + \$15/usuario | ✅ Completa |
| **3. Suscripción + complementos de funcionalidades** | Plan principal + mejoras opcionales | \$29/mes + \$19/mes de analíticas + \$9/mes de acceso a la API | ✅ Completa |
| **4. Usuarios + uso** | Tarifa por usuario + excedente por consumo | \$10/usuario/mes + \$0.05/GB después de 5 GB/usuario | ⚠️ Solución alternativa |
| **5. Suscripción + usuarios + uso** | Plataforma + usuarios + consumo (híbrido triple) | \$199/mes + \$20/usuario + excedente por uso | ⚠️ Solución alternativa |
| **6. Base escalonada + excedente por uso** | Diferentes niveles con distintas asignaciones | Starter (5K llamadas) frente a Pro (50K llamadas) + excedente | ✅ Completa |
| **7. Suscripción + cargos bajo demanda** | Tarifa recurrente + cargos manuales variables | \$99/mes de retención + facturación por hora de trabajo | ✅ Completa |
***
## Modelo híbrido 1: suscripción + uso
El modelo híbrido más común. Los clientes pagan una tarifa de suscripción base más cargos por el consumo que supera las asignaciones incluidas.
### Cómo funciona
**Plan Pro: \$49/mes**
* **Incluye**: 10,000 llamadas a la API/mes
* **Excedente**: \$0.005 por llamada después de 10,000
**Ejemplo de cálculo** (el cliente usa 25,000 llamadas este mes):
* Suscripción base: \$49.00
* Excedente: (25,000 - 10,000) × $0.005 = $75.00
* **Total: \$124.00**
### Casos de uso
* **Plataformas de API**: acceso base + cargos por solicitud
* **Servicios de IA/ML**: suscripción + uso de tokens/generación
* **Servicios de almacenamiento**: plan base + excedente por GB
* **Plataformas de comunicación**: tarifa base + cargos por mensaje/minuto
### Implementación
Configura un medidor para realizar un seguimiento de la dimensión de uso facturable.
```bash theme={null}
Dashboard: Meters → Create Meter
Event Name: "api.call"
Aggregation: Count
This tracks API calls per customer
```
Crea un producto de suscripción y vincula el medidor de uso con los precios.
```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)
```
El medidor de uso se vincula directamente al producto de suscripción. Los cargos por uso se calculan y se añaden automáticamente a la factura de suscripción.
Crea una sesión de checkout con tu producto de suscripción.
```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'
});
```
Realiza un seguimiento del uso durante el periodo de facturación.
```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' }
}]
})
});
```
### Variaciones de precios
El umbral gratuito cubre el uso incluido en la suscripción base.
**Plan Pro: \$49/mes**
* Incluye: 10,000 llamadas a la API
* Excedente: \$0.005/llamada después de 10,000
* El cliente usa 8,000 → Paga \$49 (sin excedente)
Sin tarifa base; cada unidad se factura desde el primer uso.
**Pago por uso: base de \$0/mes**
* Incluye: 0 llamadas a la API
* Uso: \$0.01/llamada desde la primera llamada
* El cliente usa 5,000 → Paga \$50
Los distintos niveles incluyen asignaciones diferentes.
* **Starter**: \$19/mes (1,000 llamadas incluidas)
* **Pro**: \$49/mes (10,000 llamadas incluidas)
* **Enterprise**: \$199/mes (100,000 llamadas incluidas)
* Todos los niveles: excedente de \$0.005/llamada
***
## Modelo híbrido 2: suscripción + usuarios
Tarifa de plataforma más cargos por usuario. Ideal para herramientas de colaboración en equipo y SaaS B2B.
### Cómo funciona
**Plan Team: $99/mes + $15/usuario**
* **Tarifa base de plataforma**: \$99/mes (incluye 3 usuarios)
* **Usuarios adicionales**: \$15/usuario/mes
**Ejemplo de cálculo** (equipo de 12 usuarios):
* Tarifa de plataforma: \$99.00
* Usuarios adicionales: (12 - 3) × $15 = $135.00
* **Total: \$234.00/mes**
### Casos de uso
* **Herramientas de colaboración**: tarifa del espacio de trabajo + tarifa por miembro
* **Sistemas CRM**: licencia de plataforma + tarifa por representante de ventas
* **Gestión de proyectos**: plan de equipo + tarifa por colaborador
* **Herramientas para desarrolladores**: tarifa de organización + tarifa por desarrollador
### Implementación
Crea un complemento para los usuarios adicionales.
```bash theme={null}
Dashboard: Products → Add-ons → Create Add-on
Name: "Additional Seat"
Price: $15/month
Description: "Add another team member"
```
Crea el producto de suscripción con la tarifa de plataforma y vincula el 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
```
Especifica la cantidad de usuarios durante el 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'
});
```
Añade o elimina usuarios de las suscripciones 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
}]
});
```
### Variaciones de precios
El plan base incluye algunos usuarios; los adicionales se cobran aparte.
**Plan Team: \$99/mes**
* Incluye: 5 usuarios
* Usuarios adicionales: \$15/usuario/mes
* 20 usuarios = \$99 + (15 × \$15) = \$324/mes
Sin tarifa de plataforma; solo se cobran los usuarios.
**Por usuario: \$25/usuario/mes**
* Sin tarifa de plataforma
* 5 usuarios = \$125/mes
* 50 usuarios = \$1,250/mes
Implementación: establece el precio de la suscripción base en \$0 y utiliza únicamente el complemento de usuarios.
El precio por usuario disminuye en los niveles superiores.
* **Starter**: \$20/usuario (1-10 usuarios)
* **Growth**: \$15/usuario (11-50 usuarios)
* **Enterprise**: \$10/usuario (51+ usuarios)
Implementación: crea productos de suscripción independientes para cada nivel con distintos precios de complementos.
***
## Modelo híbrido 3: suscripción + complementos de funcionalidades
Suscripción principal con mejoras de funcionalidades opcionales que los clientes pueden añadir.
### Cómo funciona
**Plan principal: \$29/mes**
**Complementos opcionales:**
* Analíticas avanzadas: +\$19/mes
* Acceso a la API: +\$9/mes
* Soporte prioritario: +\$29/mes
* Marca blanca: +\$49/mes
**Ejemplo de cálculo** (el cliente elige el plan principal + analíticas + acceso a la API):
* Plan principal: \$29.00
* Analíticas: \$19.00
* Acceso a la API: \$9.00
* **Total: \$57.00/mes**
### Casos de uso
* **Plataformas SaaS**: funcionalidades principales + módulos premium
* **Herramientas de marketing**: herramienta base + integraciones
* **Productos de analíticas**: panel + informes avanzados
* **Software de seguridad**: protección básica + funcionalidades avanzadas
### Implementación
Crea un complemento para cada funcionalidad 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
```
Define tu suscripción base y vincula todos los complementos de funcionalidades.
```bash theme={null}
Dashboard: Create Product → Subscription
Name: "Core Plan"
Price: $29/month
Then in Add-ons section:
- Attach all feature add-ons
```
Realiza el checkout con las funcionalidades seleccionadas.
```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'
});
```
Los clientes pueden añadir funcionalidades a las suscripciones 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: usuarios + uso
Tarifa por usuario combinada con cargos basados en el consumo. Cada usuario recibe una asignación.
**Restricción**: Dodo Payments actualmente no admite vincular medidores de uso y complementos al mismo producto de suscripción. Este modelo requiere una solución alternativa mediante lógica a nivel de aplicación.
**Próximamente**: la compatibilidad nativa con la facturación híbrida de usuarios + uso está incluida en nuestra hoja de ruta. Esto te permitirá vincular medidores de uso y complementos de usuarios al mismo producto de suscripción.
### Cómo funciona
**Analíticas de equipo: \$20/usuario/mes**
**Cada usuario incluye:**
* 5 GB de procesamiento de datos/mes
* Excedente: \$2/GB después de la asignación
**Ejemplo de cálculo** (equipo de 10 usuarios que utiliza 80 GB en total):
* Tarifas por usuario: 10 × $20 = $200.00
* Datos incluidos: 10 × 5 GB = 50 GB
* Excedente: (80 - 50) × $2 = $60.00
* **Total: \$260.00/mes**
### Casos de uso
* **Plataformas de analíticas**: tarifa por analista + procesamiento de datos
* **Herramientas de diseño**: tarifa por diseñador + almacenamiento/exportaciones
* **Entornos de desarrollo**: tarifa por desarrollador + horas de cómputo
* **Herramientas de comunicación**: tarifa por usuario + volumen de mensajes/llamadas
### Opciones de implementación
Como no puedes vincular medidores de uso y complementos a la misma suscripción, elige uno de estos enfoques:
Utiliza una suscripción basada en el uso y gestiona la facturación por usuario en tu aplicación.
```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)
```
Realiza un seguimiento del número de usuarios y calcula las tarifas por usuario por separado.
```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
});
}
```
Ajusta el uso incluido según el número de usuarios.
```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 };
}
```
Utiliza complementos para los usuarios y cobra el uso manualmente mediante cargos bajo 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()
});
}
```
Calcula y cobra manualmente los 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`
});
}
}
```
**Recomendación**: la opción B (complemento de usuarios + uso bajo demanda) suele ser más fácil de implementar porque Dodo gestiona automáticamente la facturación por usuario. Solo necesitas realizar un seguimiento de los excedentes de uso y cobrarlos.
***
## Modelo híbrido 5: suscripción + usuarios + uso (híbrido triple)
El modelo más completo: tarifa de plataforma + tarifa por usuario + consumo.
**Restricción**: Dodo Payments actualmente no admite vincular medidores de uso y complementos al mismo producto de suscripción. Este modelo requiere una solución alternativa.
**Próximamente**: la compatibilidad nativa con la facturación híbrida triple (base + usuarios + uso) está incluida en nuestra hoja de ruta. Esto te permitirá vincular medidores de uso y complementos de usuarios al mismo producto de suscripción.
### Cómo funciona
**Plataforma Enterprise**
* **Tarifa de plataforma**: \$199/mes
* **Por usuario**: \$25/usuario/mes
* **Uso**: \$0.10/1,000 llamadas a la API (50K incluidas)
**Ejemplo de cálculo** (empresa con 20 usuarios y 150,000 llamadas a la API):
* Plataforma: \$199.00
* Usuarios: 20 × $25 = $500.00
* Uso: (150K - 50K) × \$0.10/1K = \$10.00
* **Total: \$709.00/mes**
### Casos de uso
* **SaaS empresarial**: plataforma + equipo + consumo
* **Plataformas de datos**: espacio de trabajo + analistas + consultas
* **Plataformas de integración**: centro + conectores + transacciones
* **Plataformas de IA**: espacio de trabajo + desarrolladores + inferencia
### Opciones de implementación
Elige uno de estos enfoques para implementar la facturación híbrida triple:
Utiliza una suscripción con complementos de usuarios y cobra el uso manualmente mediante cargos bajo demanda.
**Este es el enfoque recomendado** porque Dodo gestiona automáticamente la tarifa de plataforma y la facturación por usuario.
```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'
});
```
Almacena los eventos de uso en tu 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()
});
}
```
Calcula y cobra los excedentes de uso mediante un cargo bajo 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`
});
}
}
```
Utiliza una suscripción con un medidor de uso y gestiona la facturación por usuario en tu aplicación.
```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
```
Realiza un seguimiento del número de usuarios y ajusta el precio de la suscripción base según corresponda.
```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()
}]
})
});
```
**Recomendación**: la opción A (base + usuarios + uso bajo demanda) suele ser más fácil porque Dodo gestiona automáticamente la facturación de la plataforma y de los usuarios. Solo necesitas realizar un seguimiento del uso y enviar los cargos al final de cada ciclo de facturación.
***
## Modelo híbrido 6: base escalonada + excedente por uso
Diferentes niveles de suscripción con distintas asignaciones incluidas y tarifas de excedente.
### Cómo funciona
| Nivel | Precio | Llamadas incluidas | Tarifa de excedente |
| -------------- | --------- | ------------------ | ------------------- |
| **Starter** | \$19/mes | 1,000 | \$0.02/llamada |
| **Pro** | \$79/mes | 25,000 | \$0.01/llamada |
| **Business** | \$199/mes | 100,000 | \$0.005/llamada |
| **Enterprise** | \$499/mes | 500,000 | \$0.002/llamada |
### Implementación
Crea productos de suscripción independientes para cada nivel, cada uno con su propia configuración 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
```
### Ruta de actualización
Cuando los clientes suben de nivel, obtienen:
* Una asignación incluida mayor
* Tarifas de excedente más bajas
* Más valor por cada 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: suscripción + cargos bajo demanda
Suscripción recurrente más cargos manuales variables por servicios o excedentes.
### Cómo funciona
**Plan de retención: \$199/mes**
**Incluye:**
* Acceso a la plataforma
* 5 horas de consultoría/mes
* Soporte por correo electrónico
**Cargos bajo demanda (según sea necesario):**
* Consultoría adicional: \$150/hora
* Desarrollo personalizado: \$200/hora
* Soporte de emergencia: \$100/incidente
**Ejemplo de cálculo** (este mes):
* Retención: \$199.00
* 3 horas adicionales de consultoría: \$450.00
* 1 servicio de soporte de emergencia: \$100.00
* **Total: \$749.00**
### Casos de uso
* **Servicios de consultoría**: retención + facturación por hora
* **Servicios gestionados**: tarifa base + cargos por incidente
* **Servicios de agencia**: tarifa mensual + cargos por proyecto
* **Planes de soporte**: tarifa de SLA + tarifa por ticket o por hora
### Implementación
Configura la suscripción con los cargos bajo demanda habilitados.
```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
}
});
```
Crea cargos cuando se presten los servicios.
```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)'
});
```
Todos los cargos aparecen en la factura del 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}`);
});
```
***
## Ejemplos del mundo real
Estos ejemplos muestran estructuras de precios ideales. Debido a la restricción de que los medidores de uso y los complementos no pueden vincularse al mismo producto, algunas combinaciones requieren soluciones alternativas (mediante cargos bajo demanda para el uso o usuarios gestionados por la aplicación).
### Ejemplo 1: plataforma SaaS de IA
**Estructura de precios:**
* **Suscripción base**: \$99/mes (acceso a la plataforma, 5 usuarios incluidos)
* **Complemento de usuarios**: \$20/usuario/mes
* **Complementos de funcionalidades**: modelos personalizados (\$49/mes), acceso a la API (\$29/mes), cola prioritaria (\$19/mes)
* **Excedente por uso**: \$0.02 por cada 1,000 tokens después de 100K (cobrado mediante cargos bajo demanda)
**Implementación**: utiliza una suscripción con complementos de usuarios y funcionalidades. Realiza un seguimiento del uso de tokens en tu aplicación y cobra los excedentes mediante cargos bajo demanda al final del ciclo de facturación.
**Ejemplo de cliente** (12 usuarios, 500K tokens, modelos personalizados + acceso a la API):
| Componente | Cálculo | Importe |
| ---------------------- | ------------------------------- | ------------- |
| Base | Tarifa de plataforma | \$99 |
| Usuarios adicionales | 7 × \$20 | \$140 |
| Modelos personalizados | Complemento | \$49 |
| Acceso a la API | Complemento | \$29 |
| Excedente de tokens | 400K × \$0.02/1K (bajo demanda) | \$8 |
| **Total** | | **\$325/mes** |
### Ejemplo 2: plataforma de herramientas para desarrolladores
**Opciones de nivel:**
| | Gratuito | Pro | Enterprise |
| ------------------ | -------- | ----------- | ---------- |
| **Precio** | \$0/mes | \$29/mes | \$199/mes |
| **Usuarios** | 1 | 5 incluidos | Ilimitados |
| **Compilaciones** | 100 | 1,000 | 10,000 |
| **Almacenamiento** | 1 GB | 10 GB | 100 GB |
**Opciones de implementación:**
**Opción A** (centrada en el uso): crea productos con medidores de uso para compilaciones/almacenamiento. Gestiona los usuarios en tu aplicación.
**Opción B** (centrada en usuarios): crea productos con complementos de usuarios. Realiza un seguimiento del uso de compilaciones/almacenamiento y cobra los excedentes mediante cargos bajo demanda.
**Complementos (si utilizas la opción B):**
* Usuarios adicionales: \$10/usuario/mes
* Compilaciones prioritarias: \$19/mes
* Dominios personalizados: \$9/dominio/mes
### Ejemplo 3: automatización de marketing
**Estructura de precios:**
* **Base**: \$79/mes (funcionalidades principales de automatización, 3 usuarios incluidos)
* **Niveles de contactos** (complementos): 1K incluidos, 5K (+\$30), 25K (+\$80), 100K (+\$200)
* **Complementos de funcionalidades**: marketing por SMS (\$29/mes), páginas de destino (\$19/mes), pruebas A/B (\$29/mes)
* **Usuarios del equipo**: complemento de \$15/usuario/mes
* **Volumen de correos electrónicos**: realiza un seguimiento en la aplicación y cobra el excedente mediante cargos bajo demanda (\$1/1,000 correos por encima del límite)
**Implementación**: utiliza una suscripción con complementos de niveles de contactos, funcionalidades y usuarios. Realiza un seguimiento de los correos enviados en tu aplicación y cobra los excedentes mediante cargos bajo demanda.
***
## Prácticas recomendadas de implementación
### Claridad de la página de precios
Haz que los precios híbridos sean fáciles de entender. Muestra claramente en tu página de precios los costes base, lo que está incluido y cómo funcionan los excedentes.
**Bueno**: "\$49/mes incluye 10,000 llamadas a la API. Llamadas adicionales: \$0.005 cada una"
**Malo**: "\$49/mes + tarifas de uso"
### Previsibilidad de costes
Ayuda a los clientes a estimar sus costes:
```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;
}
```
### Visibilidad del uso
Muestra a los clientes su uso en tiempo 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
};
});
}
```
### Transparencia de facturación
Proporciona facturas detalladas que muestren todos los componentes:
| Concepto | Importe |
| ----------------------------------------------------- | ------------ |
| Plan Pro (mensual) | \$49.00 |
| Usuarios adicionales (7 × \$15.00) | \$105.00 |
| Uso de la API - incluido (10,000 llamadas) | \$0.00 |
| Uso de la API - excedente (15,420 llamadas × \$0.005) | \$77.10 |
| Complemento de analíticas avanzadas | \$19.00 |
| **Subtotal** | **\$250.10** |
| Impuesto (8.5%) | \$21.26 |
| **Total a pagar** | **\$271.36** |
***
## Solución de problemas de facturación híbrida
**Síntomas**: el uso muestra 0 o valores incorrectos.
**Soluciones**:
1. Verifica que la ingesta de eventos funcione (comprueba las respuestas de la API)
2. Confirma que `customer_id` coincida con el cliente de la suscripción
3. Comprueba que `event_name` coincida con la configuración del medidor
4. Verifica que los eventos tengan marcas de tiempo correctas (que no estén fechadas en el futuro)
**Síntomas**: al cambiar de plan, se cobran al cliente importes inesperados.
**Soluciones**:
1. Utiliza la API `previewChangePlan` para mostrar los cargos exactos antes de confirmar
2. Comunica que la prorrata se aplica a la suscripción Y a los complementos
3. Considera utilizar `difference_immediately` para simplificar la facturación de las actualizaciones
**Síntomas**: al cliente se le cobra por un uso que debería ser gratuito.
**Soluciones**:
1. Verifica que el umbral gratuito esté configurado en el producto basado en el uso
2. Comprueba que la unidad del umbral coincida con la agregación de eventos (llamadas frente a solicitudes)
3. Confirma que el medidor de uso esté correctamente vinculado al producto de suscripción
**Síntomas**: no se pueden añadir usuarios ni funcionalidades durante el checkout.
**Soluciones**:
1. Verifica en el dashboard que los complementos estén vinculados al producto de suscripción
2. Comprueba que los ID de los complementos sean correctos en las llamadas a la API
3. Asegúrate de que la moneda del complemento coincida con la moneda del producto de suscripción
***
## Documentación relacionada
Descripción general de todos los tipos de productos y guías.
Implementación completa de la facturación por uso.
Gestión de suscripciones recurrentes.
Ampliación de suscripciones con complementos.