Hybrid Billing Models - Dodo Payments Documentation

Hybrid billing combines two or more billing models into a single pricing strategy. This lets you capture value from different dimensions—recurring fees, usage, seats, and features—while giving customers flexibility and predictability.

Usage-Based Billing

Foundation for consumption-based pricing.

Subscriptions

Foundation for recurring billing.

Add-ons

Extend subscriptions with optional upgrades.

Seat-Based Billing

Per-user pricing models.

What is Hybrid Billing?

Hybrid billing combines multiple pricing dimensions into a single product offering. Instead of choosing between flat-rate subscriptions OR usage-based pricing, you use both together.

Why Use Hybrid Billing?

Business Goal	Hybrid Solution
Predictable revenue + growth upside	Base subscription + usage overage
Team pricing that scales	Per-seat + feature add-ons
Land customers, expand later	Low base fee + consumption charges
Enterprise flexibility	Committed spend + on-demand charges
Fair pricing for variable usage	Included allowance + pay-per-use

Common Hybrid Patterns

Model	Description	Example	Native Support
1. Subscription + Usage	Base fee + consumption charges	$49/mo + $0.01/API call after 10K free	✅ Full
2. Subscription + Seats	Platform fee + per-user charges	$99/mo + $15/seat	✅ Full
3. Subscription + Feature Add-ons	Core plan + optional upgrades	$29/mo + $19/mo analytics + $9/mo API access	✅ Full
4. Seats + Usage	Per-user fee + consumption overage	$10/user/mo + $0.05/GB after 5GB/user	⚠️ Workaround
5. Subscription + Seats + Usage	Platform + users + consumption (triple hybrid)	$199/mo + $20/seat + usage overage	⚠️ Workaround
6. Tiered Base + Usage Overage	Different tiers with different allowances	Starter (5K calls) vs Pro (50K calls) + overage	✅ Full
7. Subscription + On-Demand Charges	Recurring fee + variable manual charges	$99/mo retainer + hourly billing for work	✅ Full

Hybrid Model 1: Subscription + Usage

The most common hybrid model. Customers pay a base subscription fee plus charges for consumption that exceeds included allowances.

How It Works

Pro Plan: $49/month

Included: 10,000 API calls/month
Overage: $0.005 per call after 10,000

Example calculation (customer uses 25,000 calls this month):

Base subscription: $49.00
Overage: (25,000 - 10,000) × $0.005 =$ 75.00
Total: $124.00

Use Cases

API platforms: Base access + per-request charges
AI/ML services: Subscription + token/generation usage
Storage services: Base plan + per-GB overage
Communication platforms: Base + per-message/minute charges

Implementation

Create Usage Meter

Set up a meter to track the billable usage dimension.

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

Create Subscription Product with Usage Pricing

Create a subscription product and attach the usage meter with pricing.

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)

The usage meter is attached directly to the subscription product. Usage charges are calculated and added to the subscription invoice automatically.

Create Checkout Session

Create a checkout session with your subscription product.

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

Send Usage Events

Track usage throughout the billing period.

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

Pricing Variations

Included Allowance
Zero Base + Pure Usage
Tiered Allowances

Free threshold covers usage included in base subscription.Pro Plan: $49/month

Includes: 10,000 API calls
Overage: $0.005/call after 10,000
Customer uses 8,000 → Pays $49 (no overage)

Hybrid Model 2: Subscription + Seats

Platform fee plus per-user charges. Ideal for team collaboration tools and B2B SaaS.

How It Works

Team Plan: $99/month +$ 15/seat

Base platform fee: $99/month (includes 3 seats)
Additional seats: $15/seat/month

Example calculation (team of 12 users):

Platform fee: $99.00
Extra seats: (12 - 3) × $15 =$ 135.00
Total: $234.00/month

Use Cases

Collaboration tools: Workspace fee + per-member
CRM systems: Platform license + per-sales-rep
Project management: Team plan + per-contributor
Developer tools: Organization fee + per-developer

Implementation

Create Seat Add-on

Create an add-on for additional seats.

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

Create Base Subscription

Create the subscription product with platform fee and attach the 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

Specify seat quantity during checkout.

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

Adjust Seats as Needed

Add or remove seats on existing subscriptions.

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

Pricing Variations

Included Seats
Pure Per-Seat
Tiered Per-Seat

Base plan includes some seats, charge for extras.Team Plan: $99/month

Includes: 5 seats
Extra seats: $15/seat/month
20 users = $99 + (15 × $15) = $324/month

Hybrid Model 3: Subscription + Feature Add-ons

Core subscription with optional feature upgrades customers can add.

How It Works

Core Plan: $29/month Optional Add-ons:

Advanced Analytics: +$19/month
API Access: +$9/month
Priority Support: +$29/month
White-label: +$49/month

Example calculation (customer chooses Core + Analytics + API Access):

Core plan: $29.00
Analytics: $19.00
API Access: $9.00
Total: $57.00/month

Use Cases

SaaS platforms: Core features + premium modules
Marketing tools: Base tool + integrations
Analytics products: Dashboard + advanced reports
Security software: Basic protection + advanced features

Implementation

Create Feature Add-ons

Create an add-on for each optional feature.

# 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

Define your base subscription and attach all 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

Checkout with selected features.

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

Add Features Later

Customers can add features to existing subscriptions.

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

Hybrid Model 4: Seats + Usage

Per-user fee combined with consumption-based charges. Each user gets an allowance.

Constraint: Dodo Payments does not currently support attaching both usage meters and add-ons to the same subscription product. This model requires a workaround using application-level logic.

Coming Soon: Native support for Seats + Usage hybrid billing is on our roadmap. This will allow you to attach both usage meters and seat add-ons to the same subscription product.

How It Works

Team Analytics: $20/user/month Each user includes:

5 GB data processing/month
Overage: $2/GB after allowance

Example calculation (10-user team using 80 GB total):

Seat fees: 10 × $20 =$ 200.00
Included data: 10 × 5 GB = 50 GB
Overage: (80 - 50) × $2 =$ 60.00
Total: $260.00/month

Use Cases

Analytics platforms: Per-analyst + data processing
Design tools: Per-designer + storage/exports
Development environments: Per-developer + compute hours
Communication tools: Per-user + message/call volume

Implementation Options

Since you cannot attach both usage meters and add-ons to the same subscription, choose one of these approaches:

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

Use a usage-based subscription and manage seat billing in your application.

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

Track seat count and calculate seat fees separately.

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

Adjust included usage based on seat count.

// 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 add-ons for seats and charge usage manually via on-demand charges.

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

Calculate and charge usage overages manually.

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

Recommendation: Option B (Seat Add-on + On-Demand Usage) is often easier to implement because Dodo handles seat billing automatically. You only need to track and charge usage overages.

Hybrid Model 5: Subscription + Seats + Usage (Triple Hybrid)

The most comprehensive model: platform fee + per-user + consumption.

Constraint: Dodo Payments does not currently support attaching both usage meters and add-ons to the same subscription product. This model requires a workaround approach.

Coming Soon: Native support for Triple Hybrid billing (Base + Seats + Usage) is on our roadmap. This will allow you to attach both usage meters and seat add-ons to the same subscription product.

How It Works

Enterprise Platform

Platform Fee: $199/month
Per Seat: $25/user/month
Usage: $0.10/1000 API calls (50K included)

Example calculation (company with 20 users, 150,000 API calls):

Platform: $199.00
Seats: 20 × $25 =$ 500.00
Usage: (150K - 50K) × $0.10/1K = $10.00
Total: $709.00/month

Use Cases

Enterprise SaaS: Platform + team + consumption
Data platforms: Workspace + analysts + queries
Integration platforms: Hub + connectors + transactions
AI platforms: Workspace + developers + inference

Implementation Options

Choose one of these approaches to implement triple hybrid billing:

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

Use subscription with seat add-ons, charge usage manually via on-demand charges.This is the recommended approach because Dodo handles the platform fee and seat billing automatically.

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

Track Usage in Your Application

Store usage events in your 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

Calculate and charge usage overages via on-demand charge.

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 subscription with usage meter, manage seat billing in your application.

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

Track seat count and adjust base subscription price accordingly.

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

Recommendation: Option A (Base + Seats + On-Demand Usage) is generally easier because Dodo handles platform and seat billing automatically. You only need to track usage and submit charges at the end of each billing cycle.

Hybrid Model 6: Tiered Base + Usage Overage

Different subscription tiers with different included allowances and overage rates.

How It Works

Tier	Price	Included Calls	Overage Rate
Starter	$19/month	1,000	$0.02/call
Pro	$79/month	25,000	$0.01/call
Business	$199/month	100,000	$0.005/call
Enterprise	$499/month	500,000	$0.002/call

Implementation

Create separate subscription products for each tier, each with its own usage configuration:

# 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 Path

When customers upgrade tiers, they get:

Higher included allowance
Lower overage rates
More value per dollar

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

Hybrid Model 7: Subscription + On-Demand Charges

Recurring subscription plus variable manual charges for services or overages.

How It Works

Retainer Plan: $199/month Includes:

Platform access
5 hours consulting/month
Email support

On-Demand Charges (as needed):

Extra consulting: $150/hour
Custom development: $200/hour
Emergency support: $100/incident

Example calculation (this month):

Retainer: $199.00
3 extra consulting hours: $450.00
1 emergency support: $100.00
Total: $749.00

Use Cases

Consulting services: Retainer + hourly billing
Managed services: Base fee + incident charges
Agency services: Monthly fee + project charges
Support plans: SLA fee + per-ticket or per-hour

Implementation

Create On-Demand Subscription

Set up subscription with on-demand charging enabled.

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

Charge for Services

Create charges when services are delivered.

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

All charges appear on the customer’s invoice.

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

Real-World Examples

These examples show ideal pricing structures. Due to the constraint that usage meters and add-ons cannot be attached to the same product, some combinations require workarounds (using on-demand charges for usage or app-managed seats).

Example 1: AI SaaS Platform

Pricing Structure:

Base Subscription: $99/month (platform access, 5 seats included)
Seat Add-on: $20/seat/month
Feature Add-ons: Custom Models ($49/mo), API Access ($29/mo), Priority Queue ($19/mo)
Usage Overage: $0.02 per 1,000 tokens after 100K (charged via on-demand)

Implementation: Use subscription with seat and feature add-ons. Track token usage in your application and charge overages via on-demand charges at end of billing cycle. Example Customer (12 users, 500K tokens, Custom Models + API Access):

Component	Calculation	Amount
Base	Platform fee	$99
Extra seats	7 × $20	$140
Custom Models	Add-on	$49
API Access	Add-on	$29
Token overage	400K × $0.02/1K (on-demand)	$8
Total		$325/month

Example 2: Developer Tools Platform

Tier Options:

	Free	Pro	Enterprise
Price	$0/month	$29/month	$199/month
Users	1	5 included	Unlimited
Builds	100	1,000	10,000
Storage	1 GB	10 GB	100 GB

Implementation Options: Option A (Usage-focused): Create products with usage meters for builds/storage. Manage users in your application. Option B (Seat-focused): Create products with seat add-ons. Track builds/storage usage and charge overages via on-demand. Add-ons (if using Option B):

Extra users: $10/user/month
Priority builds: $19/month
Custom domains: $9/domain/month

Example 3: Marketing Automation

Pricing Structure:

Base: $79/month (core automation features, 3 seats included)
Contact Tiers (add-ons): 1K included, 5K (+$30), 25K (+$80), 100K (+$200)
Feature Add-ons: SMS Marketing ($29/mo), Landing Pages ($19/mo), A/B Testing ($29/mo)
Team Seats: $15/user/month add-on
Email Volume: Track in application, charge overage via on-demand ($1/1,000 emails over limit)

Implementation: Use subscription with contact tier add-ons, feature add-ons, and seat add-ons. Track email sends in your application and charge overages via on-demand charges.

Implementation Best Practices

Pricing Page Clarity

Make hybrid pricing easy to understand. Show base costs, what’s included, and how overages work prominently on your pricing page.

Good: “$49/month includes 10,000 API calls. Additional calls: $0.005 each” Bad: “$49/month + usage fees”

Cost Predictability

Help customers estimate their costs:

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

Usage Visibility

Show customers their usage in real-time:

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

Billing Transparency

Provide detailed invoices showing all components:

Line Item	Amount
Pro Plan (Monthly)	$49.00
Additional Seats (7 × $15.00)	$105.00
API Usage - Included (10,000 calls)	$0.00
API Usage - Overage (15,420 calls × $0.005)	$77.10
Advanced Analytics Add-on	$19.00
Subtotal	$250.10
Tax (8.5%)	$21.26
Total Due	$271.36

Troubleshooting Hybrid Billing

Usage not being tracked correctly

Symptoms: Usage shows 0 or incorrect values.Solutions:

Verify event ingestion is working (check API responses)
Confirm customer_id matches the subscription customer
Check event_name matches the meter configuration
Verify events have correct timestamps (not future-dated)

Proration confusion with multiple components

Symptoms: Customer charged unexpected amounts when changing plans.Solutions:

Use previewChangePlan API to show exact charges before confirming
Communicate that proration applies to subscription AND add-ons
Consider using difference_immediately for simpler upgrade billing

Free threshold not applying correctly

Symptoms: Customer charged for usage that should be free.Solutions:

Verify free threshold is configured on the usage-based product
Check threshold unit matches event aggregation (calls vs. requests)
Confirm usage meter is correctly attached to the subscription product

Add-ons not appearing in checkout

Symptoms: Can’t add seats or features during checkout.Solutions:

Verify add-ons are attached to the subscription product in dashboard
Check add-on IDs are correct in API calls
Ensure add-on currency matches subscription product currency

Products

Overview of all product types and guides.

Usage-Based Billing Guide

Complete usage billing implementation.

Subscription Management

Managing recurring subscriptions.

Add-ons

Extending subscriptions with add-ons.

Usage-Based Billing

Subscriptions

Add-ons

Seat-Based Billing

​What is Hybrid Billing?

​Why Use Hybrid Billing?

​Common Hybrid Patterns

​Hybrid Model 1: Subscription + Usage

​How It Works

​Use Cases

​Implementation

​Pricing Variations

​Hybrid Model 2: Subscription + Seats

​How It Works

​Use Cases

​Implementation

​Pricing Variations

​Hybrid Model 3: Subscription + Feature Add-ons

​How It Works

​Use Cases

​Implementation

​Hybrid Model 4: Seats + Usage

​How It Works

​Use Cases

​Implementation Options

​Hybrid Model 5: Subscription + Seats + Usage (Triple Hybrid)

​How It Works

​Use Cases

​Implementation Options

​Hybrid Model 6: Tiered Base + Usage Overage

​How It Works

​Implementation

​Upgrade Path

​Hybrid Model 7: Subscription + On-Demand Charges

​How It Works

​Use Cases

​Implementation

​Real-World Examples

​Example 1: AI SaaS Platform

​Example 2: Developer Tools Platform

​Example 3: Marketing Automation

​Implementation Best Practices

​Pricing Page Clarity

​Cost Predictability

​Usage Visibility

​Billing Transparency

​Troubleshooting Hybrid Billing

​Related Documentation

Products

Usage-Based Billing Guide

Subscription Management

Add-ons

What is Hybrid Billing?

Why Use Hybrid Billing?

Common Hybrid Patterns

Hybrid Model 1: Subscription + Usage

How It Works

Use Cases

Implementation

Pricing Variations

Hybrid Model 2: Subscription + Seats

How It Works

Use Cases

Implementation

Pricing Variations

Hybrid Model 3: Subscription + Feature Add-ons

How It Works

Use Cases

Implementation

Hybrid Model 4: Seats + Usage

How It Works

Use Cases

Implementation Options

Hybrid Model 5: Subscription + Seats + Usage (Triple Hybrid)

How It Works

Use Cases

Implementation Options

Hybrid Model 6: Tiered Base + Usage Overage

How It Works

Implementation

Upgrade Path

Hybrid Model 7: Subscription + On-Demand Charges

How It Works

Use Cases

Implementation

Real-World Examples

Example 1: AI SaaS Platform

Example 2: Developer Tools Platform

Example 3: Marketing Automation

Implementation Best Practices

Pricing Page Clarity

Cost Predictability

Usage Visibility

Billing Transparency

Troubleshooting Hybrid Billing

Related Documentation