Modelle für hybride Abrechnung - Dodo Payments Documentation

Hybride Abrechnung kombiniert zwei oder mehr Abrechnungsmodelle zu einer einzigen Preisstrategie. So können Sie aus verschiedenen Dimensionen – wiederkehrenden Gebühren, Nutzung, Sitzen und Funktionen – Wert schöpfen und Ihren Kunden gleichzeitig Flexibilität und Planbarkeit bieten.

Usage-Based Billing

Grundlage für verbrauchsbasierte Preisgestaltung.

Subscriptions

Grundlage für wiederkehrende Abrechnung.

Add-ons

Abonnements mit optionalen Upgrades erweitern.

Seat-Based Billing

Preisgestaltung pro Benutzer.

Was ist hybride Abrechnung?

Hybridabrechnung kombiniert mehrere Preisdimensionen in einem einzigen Produktangebot. Anstatt zwischen Pauschalabonnements oder nutzungsbasierter Preisgestaltung zu wählen, verwenden Sie beides gemeinsam.

Warum hybride Abrechnung nutzen?

Geschäftsziel	Hybride Lösung
Planbare Einnahmen + Wachstumspotenzial	Basisabonnement + Mehrverbrauch
Skalierbare Team-Preisgestaltung	Pro Sitz + Feature-Add-ons
Kunden gewinnen, später erweitern	Niedrige Grundgebühr + Verbrauchsgebühren
Flexibilität für Unternehmen	Vereinbarte Ausgaben + On-Demand-Gebühren
Faire Preise bei variabler Nutzung	Inklusivkontingent + nutzungsabhängige Zahlung

Gängige hybride Muster

Modell	Beschreibung	Beispiel	Native Unterstützung
1. Abonnement + Nutzung	Grundgebühr + Verbrauchsgebühren	$49/Monat + $0.01/API-Aufruf nach 10K kostenlosen Aufrufen	✅ Vollständig
2. Abonnement + Sitze	Plattformgebühr + Gebühren pro Benutzer	$99/Monat + $15/Sitz	✅ Vollständig
3. Abonnement + Feature-Add-ons	Basisplan + optionale Erweiterungen	$29/Monat + $19/Monat für Analytics + $9/Monat für API-Zugriff	✅ Vollständig
4. Sitze + Nutzung	Gebühr pro Benutzer + Verbrauchsüberschreitung	$10/Benutzer/Monat + $0.05/GB nach 5 GB/Benutzer	⚠️ Workaround
5. Abonnement + Sitze + Nutzung	Plattform + Benutzer + Verbrauch	$199/Monat + $20/Sitz + Verbrauchsüberschreitung	⚠️ Workaround
6. Gestaffelte Basis + Nutzungsüberschreitung	Verschiedene Stufen mit unterschiedlichen Kontingenten	Starter (5K Aufrufe) gegenüber Pro (50K Aufrufe) + Überschreitung	✅ Vollständig
7. Abonnement + On-Demand-Gebühren	Wiederkehrende Gebühr + variable manuelle Gebühren	$99/Monat Retainer + stündliche Abrechnung für Arbeiten	✅ Vollständig

Hybrides Modell 1: Abonnement + Nutzung

Das häufigste hybride Modell. Kunden zahlen eine Grundgebühr für das Abonnement sowie Gebühren für den Verbrauch, der die enthaltenen Kontingente überschreitet.

Funktionsweise

Pro-Plan: $49/Monat

Enthalten: 10.000 API-Aufrufe/Monat
Überschreitung: $0.005 pro Aufruf nach 10.000

Beispielberechnung (Kunde verwendet diesen Monat 25.000 Aufrufe):

Basisabonnement: $49.00
Überschreitung: (25.000 - 10.000) × $0.005 = $75.00
Gesamt: $124.00

Anwendungsfälle

API-Plattformen: Basiszugriff + Gebühren pro Anfrage
KI/ML-Dienste: Abonnement + Token-/Generierungsnutzung
Speicherdienste: Basistarif + Mehrverbrauch pro GB
Kommunikationsplattformen: Basis + Gebühren pro Nachricht/Minute

Implementierung

Create Usage Meter

Richten Sie einen Meter ein, um die abrechenbare Nutzungsdimension zu erfassen.

Dashboard: Meters → Create Meter
Event Name: "api.call"
Aggregation: Count
This tracks API calls per customer

Create Subscription Product with Usage Pricing

Erstellen Sie ein Abonnementprodukt und verknüpfen Sie den Usage Meter mit der Preisgestaltung.

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)

Der Usage Meter wird direkt mit dem Abonnementprodukt verknüpft. Nutzungsgebühren werden automatisch berechnet und zur Abonnementrechnung hinzugefügt.

Create Checkout Session

Erstellen Sie eine Checkout-Session mit Ihrem Abonnementprodukt.

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_pro_plan', quantity: 1 }
  ],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yourapp.com/success'
});

Send Usage Events

Erfassen Sie die Nutzung während des Abrechnungszeitraums.

await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
    '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' }
    }]
  })
});

Preisvarianten

Included Allowance
Zero Base + Pure Usage
Tiered Allowances

Das kostenlose Kontingent deckt die im Basisabonnement enthaltene Nutzung ab.Pro-Plan: $49/Monat

Enthalten: 10.000 API-Aufrufe
Überschreitung: $0.005/Aufruf nach 10.000
Kunde verwendet 8.000 → Zahlt $49 (keine Überschreitung)

Hybrides Modell 2: Abonnement + Sitze

Plattformgebühr plus Gebühren pro Benutzer. Ideal für Tools zur Teamzusammenarbeit und B2B-SaaS.

Funktionsweise

Team-Plan: $99/Monat + $15/Sitz

Basisplattformgebühr: $99/Monat (3 Sitze enthalten)
Zusätzliche Sitze: $15/Sitz/Monat

Beispielberechnung (Team mit 12 Benutzern):

Plattformgebühr: $99.00
Zusätzliche Sitze: (12 - 3) × $15 = $135.00
Gesamt: $234.00/Monat

Anwendungsfälle

Tools zur Zusammenarbeit: Arbeitsbereichsgebühr + pro Mitglied
CRM-Systeme: Plattformlizenz + pro Vertriebsmitarbeiter
Projektmanagement: Team-Plan + pro Mitwirkendem
Entwicklertools: Organisationsgebühr + pro Entwickler

Implementierung

Create Seat Add-on

Erstellen Sie ein Add-on für zusätzliche Sitze.

Dashboard: Products → Add-ons → Create Add-on
Name: "Additional Seat"
Price: $15/month
Description: "Add another team member"

Create Base Subscription

Erstellen Sie das Abonnementprodukt mit Plattformgebühr und verknüpfen Sie das Add-on.

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

Create Checkout with Seats

Geben Sie die Sitzanzahl während des Checkouts an.

const session = await client.checkoutSessions.create({
  product_cart: [{
    product_id: 'pdt_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'
});

Adjust Seats as Needed

Fügen Sie Sitze zu bestehenden Abonnements hinzu oder entfernen Sie sie.

// Add 5 more seats
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [{
    addon_id: 'addon_seat',
    quantity: 14  // New total: 14 extra seats
  }]
});

Preisvarianten

Included Seats
Pure Per-Seat
Tiered Per-Seat

Der Basistarif enthält einige Sitze; zusätzliche Sitze werden berechnet.Team-Plan: $99/Monat

Enthalten: 5 Sitze
Zusätzliche Sitze: $15/Sitz/Monat
20 Benutzer = $99 + (15 × $15) = $324/Monat

Hybrides Modell 3: Abonnement + Feature-Add-ons

Kernabonnement mit optionalen Funktionserweiterungen, die Kunden hinzufügen können.

Funktionsweise

Basisplan: $29/Monat Optionale Add-ons:

Erweiterte Analytics: +$19/Monat
API-Zugriff: +$9/Monat
Priorisierter Support: +$29/Monat
White-Label: +$49/Monat

Beispielberechnung (Kunde wählt Basis + Analytics + API-Zugriff):

Basisplan: $29.00
Analytics: $19.00
API-Zugriff: $9.00
Gesamt: $57.00/Monat

Anwendungsfälle

SaaS-Plattformen: Kernfunktionen + Premium-Module
Marketingtools: Basistool + Integrationen
Analytics-Produkte: Dashboard + erweiterte Berichte
Sicherheitssoftware: Basisschutz + erweiterte Funktionen

Implementierung

Create Feature Add-ons

Erstellen Sie für jede optionale Funktion ein Add-on.

# 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

Create Core Subscription

Definieren Sie Ihr Basisabonnement und verknüpfen Sie alle Feature-Add-ons.

Dashboard: Create Product → Subscription
Name: "Core Plan"
Price: $29/month

Then in Add-ons section:
- Attach all feature add-ons

Let Customers Choose

Führen Sie den Checkout mit den ausgewählten Funktionen durch.

const session = await client.checkoutSessions.create({
  product_cart: [{
    product_id: 'pdt_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'
});

Add Features Later

Kunden können Funktionen zu bestehenden Abonnements hinzufügen.

// Customer wants to add Priority Support
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_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!
  ]
});

Hybrides Modell 4: Sitze + Nutzung

Gebühr pro Benutzer kombiniert mit verbrauchsabhängigen Gebühren. Jeder Benutzer erhält ein Kontingent.

Einschränkung: Dodo Payments unterstützt derzeit nicht die gleichzeitige Verknüpfung von Usage Meters und Add-ons mit demselben Abonnementprodukt. Dieses Modell erfordert einen Workaround mit Logik auf Anwendungsebene.

So funktioniert es

Team-Analytics: $20/Benutzer/Monat Jeder Benutzer umfasst:

5 GB Datenverarbeitung/Monat
Überschreitung: $2/GB nach dem Kontingent

Beispielberechnung (Team mit 10 Benutzern und insgesamt 80 GB Nutzung):

Sitzgebühren: 10 × $20 = $200.00
Enthaltene Daten: 10 × 5 GB = 50 GB
Überschreitung: (80 - 50) × $2 = $60.00
Gesamt: $260.00/Monat

Anwendungsfälle

Analytics-Plattformen: Pro Analyst + Datenverarbeitung
Designtools: Pro Designer + Speicher/Exporte
Entwicklungsumgebungen: Pro Entwickler + Rechenstunden
Kommunikationstools: Pro Benutzer + Nachrichten-/Anrufvolumen

Implementierungsoptionen

Da du nicht sowohl Nutzungszähler als auch Add-ons an dasselbe Abonnement anhängen kannst, wähle einen der folgenden Ansätze:

Option A: Usage Product + App-Managed Seats
Option B: Seat Add-on + On-Demand Usage Charges

Verwende ein nutzungsbasiertes Abonnement und verwalte die Abrechnung der Sitze in deiner Anwendung.

Create Usage Meter

Dashboard: Meters → Create Meter
Event Name: "data.processed"
Aggregation: Sum
Property: "bytes"

Create Usage-Based Subscription

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)

Manage Seats in Your Application

Verfolge die Sitzanzahl und berechne die Sitzgebühren separat.

// 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
  });
}

Calculate Dynamic Free Threshold

Passe die enthaltene Nutzung basierend auf der Sitzanzahl an.

// 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 };
}

Verwende Add-ons für Sitze und berechne die Nutzung manuell über On-Demand-Gebühren.

Create Seat Add-on

Dashboard: Products → Add-ons → Create Add-on
Name: "Team Member"
Price: $20/month

Create Subscription with Add-on

Dashboard: Create Product → Subscription
Name: "Team Analytics"
Base Price: $0/month

Attach add-on:
- "Team Member" add-on

Enable on-demand charging

Track Usage in Your Application

// 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()
  });
}

Charge Usage at End of Cycle

Berechne und belaste Nutzungsüberschreitungen manuell.

async function billUsageOverage(subscriptionId: string) {
  const subscription = await getSubscription(subscriptionId);
  const seatCount = subscription.addons.find(a => a.addon_id === 'addon_seat')?.quantity || 0;

  const includedGB = seatCount * 5;
  const usedGB = await calculatePeriodUsage(subscription.customer.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`
    });
  }
}

Empfehlung: Option B (Sitz-Add-on + On-Demand-Nutzung) ist häufig einfacher zu implementieren, da Dodo die Sitzabrechnung automatisch übernimmt. Du musst nur Nutzungsüberschreitungen verfolgen und abrechnen.

Hybridmodell 5: Abonnement + Sitze + Nutzung (Triple Hybrid)

Das umfassendste Modell: Plattformgebühr + pro Benutzer + Verbrauch.

Einschränkung: Dodo Payments unterstützt derzeit nicht, sowohl Nutzungszähler als auch Add-ons an dasselbe Abonnementprodukt anzuhängen. Für dieses Modell ist ein Workaround erforderlich.

So funktioniert es

Enterprise-Plattform

Plattformgebühr: $199/Monat
Pro Sitz: $25/Benutzer/Monat
Nutzung: $0.10/1000 API-Aufrufe (50K enthalten)

Beispielberechnung (Unternehmen mit 20 Benutzern und 150.000 API-Aufrufen):

Plattform: $199.00
Sitze: 20 × $25 = $500.00
Nutzung: (150K - 50K) × $0.10/1K = $10.00
Gesamt: $709.00/Monat

Anwendungsfälle

Enterprise-SaaS: Plattform + Team + Verbrauch
Datenplattformen: Arbeitsbereich + Analysten + Abfragen
Integrationsplattformen: Hub + Konnektoren + Transaktionen
KI-Plattformen: Arbeitsbereich + Entwickler + Inferenz

Implementierungsoptionen

Wähle einen der folgenden Ansätze zur Implementierung der Triple-Hybrid-Abrechnung:

Option A: Base + Seats (Add-on) + On-Demand Usage
Option B: Base + Usage (Meter) + App-Managed Seats

Verwende ein Abonnement mit Sitz-Add-ons und berechne die Nutzung manuell über On-Demand-Gebühren.Dies ist der empfohlene Ansatz, da Dodo die Plattformgebühr und Sitzabrechnung automatisch übernimmt.

Create Seat Add-on

Dashboard: Products → Add-ons → Create Add-on
Name: "User Seat"
Price: $25/month

Create Subscription Product

Dashboard: Create Product → Subscription
Name: "Enterprise Platform"
Base Price: $199/month

Attach add-on:
- "User Seat" add-on

Enable on-demand charging

Create Checkout with Seats

const session = await client.checkoutSessions.create({
  product_cart: [{
    product_id: 'pdt_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'
});

Track Usage in Your Application

Speichere Nutzungsereignisse in deinem System.

// 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()
  });
}

Charge Usage at End of Cycle

Berechne und belaste Nutzungsüberschreitungen über eine On-Demand-Gebühr.

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`
    });
  }
}

Verwende ein Abonnement mit Nutzungszähler und verwalte die Sitzabrechnung in deiner Anwendung.

Create Usage Meter

Dashboard: Meters → Create Meter
Event Name: "api.call"
Aggregation: Count

Create Subscription Product with Usage

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

Manage Seats in Your Application

Verfolge die Sitzanzahl und passe den Preis des Basisabonnements entsprechend an.

// 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
}

Send Usage Events to Dodo

await fetch('https://test.dodopayments.com/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`,
    '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()
    }]
  })
});

Empfehlung: Option A (Basis + Sitze + On-Demand-Nutzung) ist im Allgemeinen einfacher, da Dodo die Plattform- und Sitzabrechnung automatisch übernimmt. Du musst nur die Nutzung verfolgen und am Ende jedes Abrechnungszeitraums Gebühren übermitteln.

Hybridmodell 6: Gestaffelte Basis + Nutzungsüberschreitung

Verschiedene Abonnementstufen mit unterschiedlichen enthaltenen Kontingenten und Überschreitungssätzen.

So funktioniert es

Stufe	Preis	Enthaltene Aufrufe	Überschreitungsrate
Starter	$19/Monat	1.000	$0.02/Aufruf
Pro	$79/Monat	25.000	$0.01/Aufruf
Business	$199/Monat	100.000	$0.005/Aufruf
Enterprise	$499/Monat	500.000	$0.002/Aufruf

Implementierung

Erstelle separate Abonnementprodukte für jede Stufe, jeweils mit eigener Nutzungskonfiguration:

# 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

Upgrade-Pfad

Beim Upgrade auf eine höhere Stufe erhalten Kunden:

Ein höheres enthaltenes Kontingent
Niedrigere Sätze für Überschreitungen
Mehr Wert pro Dollar

// Customer upgrades from Starter to Pro
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

Hybridmodell 7: Abonnement + On-Demand-Gebühren

Wiederkehrendes Abonnement plus variable manuelle Gebühren für Services oder Überschreitungen.

So funktioniert es

Retainer-Plan: $199/Monat Enthalten:

Plattformzugang
5 Beratungsstunden/Monat
E-Mail-Support

On-Demand-Gebühren (nach Bedarf):

Zusätzliche Beratung: $150/Stunde
Individuelle Entwicklung: $200/Stunde
Notfall-Support: $100/Vorfall

Beispielberechnung (diesen Monat):

Retainer: $199.00
3 zusätzliche Beratungsstunden: $450.00
1 Notfall-Support: $100.00
Gesamt: $749.00

Anwendungsfälle

Beratungsservices: Retainer + Abrechnung nach Stunden
Managed Services: Grundgebühr + Vorfallgebühren
Agenturservices: Monatsgebühr + Projektgebühren
Supportpläne: SLA-Gebühr + pro Ticket oder Stunde

Implementierung

Create On-Demand Subscription

Richte ein Abonnement mit aktivierter On-Demand-Abrechnung ein.

// Note: POST /subscriptions is deprecated — prefer checkout sessions for new integrations
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: 'pdt_retainer',
  quantity: 1,
  payment_link: true,
  return_url: 'https://yourapp.com/success',
  on_demand: {
    mandate_only: false,
    product_price: 19900  // $199 initial charge
  }
});

Charge for Services

Erstelle Gebühren, sobald Services erbracht wurden.

// 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)'
});

Track and Invoice

Alle Gebühren erscheinen auf der Rechnung des Kunden.

// 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.payment_id}: $${payment.total_amount / 100}`);
});

Beispiele aus der Praxis

Diese Beispiele zeigen ideale Preisstrukturen. Aufgrund der Einschränkung, dass Nutzungszähler und Add-ons nicht an dasselbe Produkt angehängt werden können, erfordern einige Kombinationen Workarounds (On-Demand-Gebühren für die Nutzung oder von der Anwendung verwaltete Sitze).

Beispiel 1: KI-SaaS-Plattform

Preisstruktur:

Basisabonnement: $99/Monat (Plattformzugriff, 5 Sitze enthalten)
Sitz-Add-on: $20/Sitz/Monat
Feature-Add-ons: Custom Models ($49/Monat), API-Zugriff ($29/Monat), Prioritätswarteschlange ($19/Monat)
Nutzungsüberschreitung: $0.02 pro 1.000 Token nach 100K (über On-Demand abgerechnet)

Implementierung: Verwenden Sie ein Abonnement mit Sitz- und Feature-Add-ons. Erfassen Sie die Token-Nutzung in Ihrer Anwendung und berechnen Sie Überschreitungen am Ende des Abrechnungszeitraums über On-Demand-Gebühren. Beispielkunde (12 Benutzer, 500K Token, Custom Models + API-Zugriff):

Komponente	Berechnung	Betrag
Basis	Plattformgebühr	$99
Zusätzliche Sitze	7 × $20	$140
Custom Models	Add-on	$49
API-Zugriff	Add-on	$29
Token-Überschreitung	400K × $0.02/1K (On-Demand)	$8
Gesamt		$325/Monat

Beispiel 2: Plattform für Entwicklertools

Stufenoptionen:

	Kostenlos	Pro	Enterprise
Preis	$0/Monat	$29/Monat	$199/Monat
Benutzer	1	5 enthalten	Unbegrenzt
Builds	100	1.000	10.000
Speicher	1 GB	10 GB	100 GB

Implementierungsoptionen: Option A (Nutzungsorientiert): Erstelle Produkte mit Nutzungszählern für Builds/Speicher. Verwalte Benutzer in deiner Anwendung. Option B (Sitzorientiert): Erstelle Produkte mit Sitz-Add-ons. Verfolge die Nutzung von Builds/Speicher und berechne Überschreitungen über On-Demand. Add-ons (bei Verwendung von Option B):

Zusätzliche Benutzer: $10/Benutzer/Monat
Priorisierte Builds: $19/Monat
Benutzerdefinierte Domains: $9/Domain/Monat

Beispiel 3: Marketingautomatisierung

Preisstruktur:

Basis: $79/Monat (zentrale Automatisierungsfunktionen, 3 Sitze enthalten)
Kontaktstufen (Add-ons): 1K enthalten, 5K (+$30), 25K (+$80), 100K (+$200)
Feature-Add-ons: SMS-Marketing ($29/Monat), Landingpages ($19/Monat), A/B-Testing ($29/Monat)
Team-Sitze: $15/Benutzer/Monat als Add-on
E-Mail-Volumen: In der Anwendung erfassen, Überschreitungen über On-Demand abrechnen ($1/1.000 E-Mails über dem Limit)

Implementierung: Verwenden Sie ein Abonnement mit Kontaktstufen-, Feature- und Sitz-Add-ons. Erfassen Sie den E-Mail-Versand in Ihrer Anwendung und berechnen Sie Überschreitungen am Ende des Abrechnungszeitraums über On-Demand-Gebühren.

Best Practices für die Implementierung

Klarheit auf der Preisseite

Mache hybride Preise leicht verständlich. Zeige die Basiskosten, die enthaltenen Leistungen und die Funktionsweise von Überschreitungen prominent auf deiner Preisseite.

Klar: “$49/Monat umfasst 10.000 API-Aufrufe. Zusätzliche Aufrufe: $0.005 pro Aufruf” Unklar: “$49/Monat + Nutzungsgebühren”

Kostenplanbarkeit

Hilf Kunden, ihre Kosten zu schätzen:

// 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;
}

Nutzungstransparenz

Zeige Kunden ihre Nutzung in Echtzeit:

// 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
    };
  });
}

Transparente Abrechnung

Stelle detaillierte Rechnungen bereit, auf denen alle Bestandteile aufgeführt sind:

Position	Betrag
Pro-Plan (monatlich)	$49.00
Zusätzliche Sitze (7 × $15.00)	$105.00
API-Nutzung – enthalten (10.000 Aufrufe)	$0.00
API-Nutzung – Überschreitung (15.420 Aufrufe × $0.005)	$77.10
Add-on für erweiterte Analytics	$19.00
Zwischensumme	$250.10
Steuer (8.5%)	$21.26
Zu zahlender Gesamtbetrag	$271.36

Fehlerbehebung bei hybrider Abrechnung

Usage not being tracked correctly

Symptome: Die Nutzung wird mit 0 oder falschen Werten angezeigt.Lösungen:

Überprüfe, ob die Ereigniserfassung funktioniert (API-Antworten prüfen)
Bestätige, dass customer_id mit dem Abonnementkunden übereinstimmt
Überprüfe, dass event_name mit der Zählerkonfiguration übereinstimmt
Überprüfe, ob die Ereignisse korrekte Zeitstempel haben (nicht auf ein zukünftiges Datum datiert)

Proration confusion with multiple components

Symptome: Dem Kunden werden beim Tarifwechsel unerwartete Beträge berechnet.Lösungen:

Verwende die previewChangePlan API, um die genauen Gebühren vor der Bestätigung anzuzeigen
Kommuniziere, dass die anteilige Abrechnung sowohl für das Abonnement ALS AUCH für Add-ons gilt
Ziehe difference_immediately für eine einfachere Upgrade-Abrechnung in Betracht

Free threshold not applying correctly

Symptome: Dem Kunden wird Nutzung berechnet, die kostenlos sein sollte.Lösungen:

Überprüfe, ob der kostenlose Schwellenwert beim nutzungsbasierten Produkt konfiguriert ist
Überprüfe, ob die Einheit des Schwellenwerts mit der Ereignisaggregation übereinstimmt (Aufrufe vs. Anfragen)
Bestätige, dass der Nutzungszähler korrekt an das Abonnementprodukt angehängt ist

Add-ons not appearing in checkout

Symptome: Sitze oder Features können während des Checkouts nicht hinzugefügt werden.Lösungen:

Überprüfe, ob die Add-ons im Dashboard an das Abonnementprodukt angehängt sind
Überprüfe, ob die Add-on-IDs in API-Aufrufen korrekt sind
Stelle sicher, dass die Währung des Add-ons mit der Währung des Abonnementprodukts übereinstimmt

Products

Übersicht über alle Produkttypen und Anleitungen.

Usage-Based Billing Guide

Vollständige Implementierung der nutzungsbasierten Abrechnung.

Subscription Management

Verwaltung wiederkehrender Abonnements.

Add-ons

Erweiterung von Abonnements mit Add-ons.

Usage-Based Billing

Subscriptions

Add-ons

Seat-Based Billing

​Was ist hybride Abrechnung?

​Warum hybride Abrechnung nutzen?

​Gängige hybride Muster

​Hybrides Modell 1: Abonnement + Nutzung

​Funktionsweise

​Anwendungsfälle

​Implementierung

​Preisvarianten

​Hybrides Modell 2: Abonnement + Sitze

​Funktionsweise

​Anwendungsfälle

​Implementierung

​Preisvarianten

​Hybrides Modell 3: Abonnement + Feature-Add-ons

​Funktionsweise

​Anwendungsfälle

​Implementierung

​Hybrides Modell 4: Sitze + Nutzung

​So funktioniert es

​Anwendungsfälle

​Implementierungsoptionen

​Hybridmodell 5: Abonnement + Sitze + Nutzung (Triple Hybrid)

​So funktioniert es

​Anwendungsfälle

​Implementierungsoptionen

​Hybridmodell 6: Gestaffelte Basis + Nutzungsüberschreitung

​So funktioniert es

​Implementierung

​Upgrade-Pfad

​Hybridmodell 7: Abonnement + On-Demand-Gebühren

​So funktioniert es

​Anwendungsfälle

​Implementierung

​Beispiele aus der Praxis

​Beispiel 1: KI-SaaS-Plattform

​Beispiel 2: Plattform für Entwicklertools

​Beispiel 3: Marketingautomatisierung

​Best Practices für die Implementierung

​Klarheit auf der Preisseite

​Kostenplanbarkeit

​Nutzungstransparenz

​Transparente Abrechnung

​Fehlerbehebung bei hybrider Abrechnung

​Verwandte Dokumentation

Products

Usage-Based Billing Guide

Subscription Management

Add-ons

Was ist hybride Abrechnung?

Warum hybride Abrechnung nutzen?

Gängige hybride Muster

Hybrides Modell 1: Abonnement + Nutzung

Funktionsweise

Anwendungsfälle

Implementierung

Preisvarianten

Hybrides Modell 2: Abonnement + Sitze

Funktionsweise

Anwendungsfälle

Implementierung

Preisvarianten

Hybrides Modell 3: Abonnement + Feature-Add-ons

Funktionsweise

Anwendungsfälle

Implementierung

Hybrides Modell 4: Sitze + Nutzung

So funktioniert es

Anwendungsfälle

Implementierungsoptionen

Hybridmodell 5: Abonnement + Sitze + Nutzung (Triple Hybrid)

So funktioniert es

Anwendungsfälle

Implementierungsoptionen

Hybridmodell 6: Gestaffelte Basis + Nutzungsüberschreitung

So funktioniert es

Implementierung

Upgrade-Pfad

Hybridmodell 7: Abonnement + On-Demand-Gebühren

So funktioniert es

Anwendungsfälle

Implementierung

Beispiele aus der Praxis

Beispiel 1: KI-SaaS-Plattform

Beispiel 2: Plattform für Entwicklertools

Beispiel 3: Marketingautomatisierung

Best Practices für die Implementierung

Klarheit auf der Preisseite

Kostenplanbarkeit

Nutzungstransparenz

Transparente Abrechnung

Fehlerbehebung bei hybrider Abrechnung

Verwandte Dokumentation