Seat-Based Billing - Dodo Payments Documentation

Seat-based billing lets you charge customers based on the number of users, team members, or licenses they need. It’s the standard pricing model for team collaboration tools, enterprise software, and B2B SaaS products.

Implementation Tutorial

Step-by-step guide with code examples.

Add-ons Documentation

Learn about the add-on system that powers seat-based billing.

Subscription Management

Manage seat-based subscriptions and plan changes.

Webhooks

Track seat changes with subscription webhooks.

What is Seat-Based Billing?

Seat-based billing (also called per-user or per-seat pricing) charges customers based on the number of users who access your product. Instead of a flat fee, the price scales with team size.

Common Use Cases

Industry	Example	Pricing Model
Team Collaboration	Slack, Notion, Asana	Per active user/month
Developer Tools	GitHub, GitLab, Jira	Per seat/month
CRM Software	Salesforce, HubSpot	Per user license
Design Tools	Figma, Canva	Per editor seat
Security Software	1Password, Okta	Per user/month
Video Conferencing	Zoom, Teams	Per host license

Benefits of Seat-Based Pricing

For Your Business:

Revenue scales naturally as customers grow
Predictable pricing customers can budget for
Clear upgrade path from individual to team to enterprise
Higher lifetime value as teams expand

For Your Customers:

Pay only for what they use
Easy to understand and forecast costs
Flexibility to add/remove users as needed
Fair pricing that matches team size

How Seat-Based Billing Works in Dodo Payments

Dodo Payments implements seat-based billing using the Add-ons system. Here’s how it works:

Architecture Overview

A Team Pro subscription costs $99/month and includes 5 seats. If you have more than 5 users, you pay an additional $15/month for each extra seat. For example, if your team needs 15 seats:

Base Plan: $99/month (includes 5 seats)
Add-ons: 10 extra seats × $15/month = $150/month
Total monthly cost: $99 + $150 = $249 for 15 seats

Key Components

Component	Purpose	Example
Base Product	Core subscription with included seats	”Team Plan - $99/month (5 seats included)“
Seat Add-on	Per-seat charge for additional users	”Extra Seat - $15/month each”
Quantity	Number of additional seats purchased	10 extra seats

Pricing Strategies

Choose the seat-based pricing strategy that fits your business:

Strategy 1: Base + Per-Seat Add-on

Include a set number of seats in the base plan, charge for additional seats. Example:

Starter Plan: $49/month
├── Includes: 3 seats
├── Extra seats: $10/month each
└── 8 total seats = $49 + (5 × $10) = $99/month

Best for: Products where small teams can function with the base offering.

Strategy 2: Pure Per-Seat Pricing

Charge a flat rate per seat with no base fee. Example:

Per User: $12/month
├── 5 users = $60/month
├── 20 users = $240/month
└── 100 users = $1,200/month

Implementation: Set base plan price to $0, use only the seat add-on. Best for: Simple, transparent pricing; usage-based models.

Strategy 3: Tiered Seat Pricing

Different base plans with different per-seat rates. Example:

Starter: $0/month base + $15/seat
├── Lower features, higher per-seat cost

Professional: $99/month base + $10/seat
├── More features, lower per-seat cost

Enterprise: $499/month base + $7/seat
└── All features, volume discount on seats

Implementation: Create separate products for each tier with different add-on prices. Best for: Encouraging upgrades to higher tiers; enterprise sales.

Strategy 4: Seat Bundles

Sell seats in packs rather than individually. Example:

5-Seat Pack: $50/month ($10/seat)
10-Seat Pack: $80/month ($8/seat)
25-Seat Pack: $175/month ($7/seat)

Implementation: Create multiple add-ons for different pack sizes. Best for: Simplifying purchasing decisions; encouraging larger commitments.

Setting Up Seat-Based Billing

Step 1: Plan Your Pricing

Before implementation, define your pricing structure:

Define Base Plan

Decide what’s included in the base subscription:

Base price (can be $0 for pure per-seat)
Number of included seats
Features available at this tier

Set Seat Pricing

Determine the per-seat add-on cost:

Price per additional seat
Any volume discounts (via multiple add-ons)
Maximum seats allowed (if applicable)

Consider Billing Frequency

Align seat pricing with your billing cycle:

Monthly subscriptions → monthly seat charges
Annual subscriptions → annual seat charges (often discounted)

Step 2: Create the Seat Add-on

In your Dodo Payments dashboard:

Navigate to Products → Add-Ons
Click Create Add-On
Configure the add-on:

Field	Value	Notes
Name	”Additional Seat” or “Team Member”	Clear, user-friendly name
Description	”Add another team member to your workspace”	Explain what customers get
Price	Your per-seat price	e.g., $10.00
Currency	Match your base product	Must be the same currency
Tax Category	Same as base product	Ensures consistent tax handling

Create descriptive add-on names that make sense on invoices. “Additional Team Seat” is clearer than “Seat Add-on” for customers reviewing their bills.

Step 3: Create the Base Subscription

Create your subscription product:

Navigate to Products → Create Product
Select Subscription
Configure pricing and details
In the Add-Ons section, attach your seat add-on

Step 4: Attach Add-on to Product

Link the seat add-on to your subscription:

Edit your subscription product
Scroll to Add-Ons section
Click Add Add-Ons
Select your seat add-on
Save changes

Your subscription product now supports seat-based pricing. Customers can purchase any quantity of additional seats during checkout.

Managing Seats

Adding Seats to New Subscriptions

When creating a checkout session, specify the seat quantity:

const session = await client.checkoutSessions.create({
  product_cart: [{
    product_id: 'prod_team_plan',
    quantity: 1,
    addons: [{
      addon_id: 'addon_seat',
      quantity: 10  // 10 additional seats
    }]
  }],
  customer: { email: '[email protected]' },
  return_url: 'https://yourapp.com/success'
});

Changing Seat Count on Existing Subscriptions

Use the Change Plan API to adjust seats:

// Add 5 more seats to existing subscription
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [{
    addon_id: 'addon_seat',
    quantity: 15  // New total: 15 additional seats
  }]
});

Removing Seats

To reduce seat count, specify the lower quantity:

// Reduce from 15 to 8 additional seats
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_team_plan',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{
    addon_id: 'addon_seat',
    quantity: 8  // Reduced to 8 additional seats
  }]
});

Removing All Additional Seats

Pass an empty addons array to remove all add-ons:

// Remove all additional seats, keep only base plan seats
await client.subscriptions.changePlan('sub_123', {
  product_id: 'prod_team_plan',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: []  // Removes all add-ons
});

Proration for Seat Changes

When customers add or remove seats mid-cycle, proration determines how they’re billed.

Proration Modes

Mode	Adding Seats	Removing Seats
`prorated_immediately`	Charge for remaining days in cycle	Credit for unused days
`difference_immediately`	Charge full seat price	Credit applied to future renewals
`full_immediately`	Charge full seat price, reset billing cycle	No credit

Proration Examples

Scenario: 15-day billing cycle remaining, adding 5 seats at $10/seat

prorated_immediately
difference_immediately
full_immediately

Prorated charge = ($10 × 5 seats) × (15 days / 30 days)
                = $50 × 0.5
                = $25 immediate charge

Customer pays $25 now, then $50/month on renewal.

Immediate charge = $10 × 5 seats = $50

Customer pays full $50 now, regardless of cycle position.

Immediate charge = Full subscription + add-ons
Billing cycle resets to today

Customer pays full amount, new billing cycle starts.

Preview Before Changing

Always preview proration before making changes:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'prod_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [{ addon_id: 'addon_seat', quantity: 20 }]
});

console.log('Immediate charge:', preview.immediate_charge.summary);
// Show customer: "Adding 5 seats will cost $25 today"

Tracking Seats with Webhooks

Monitor seat changes by listening to subscription webhooks:

Relevant Events

Event	When Triggered	Use Case
`subscription.active`	New subscription activated	Provision initial seats
`subscription.plan_changed`	Seats added/removed	Update seat count in your app
`subscription.renewed`	Subscription renewed	Confirm seat count unchanged
`subscription.cancelled`	Subscription cancelled	Deprovision all seats

Webhook Handler Example

app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'subscription.active':
      // New subscription - provision seats
      const seats = calculateTotalSeats(event.data);
      await provisionSeats(event.data.customer_id, seats);
      break;

    case 'subscription.plan_changed':
      // Seats changed - update access
      const newSeats = calculateTotalSeats(event.data);
      await updateSeatCount(event.data.subscription_id, newSeats);
      break;

    case 'subscription.cancelled':
      // Subscription cancelled - deprovision
      await deprovisionAllSeats(event.data.subscription_id);
      break;
  }

  res.json({ received: true });
});

function calculateTotalSeats(subscriptionData) {
  const baseSeats = 5;  // Included in plan
  const addonSeats = subscriptionData.addons?.reduce(
    (total, addon) => total + addon.quantity, 0
  ) || 0;
  return baseSeats + addonSeats;
}

Enforcing Seat Limits

Your application must enforce seat limits. Dodo Payments tracks billing, but you control access.

Enforcement Strategies

Hard Limit
Soft Limit with Warning
Auto-Upgrade

Strictly prevent adding users beyond the seat count.

async function inviteUser(teamId: string, email: string) {
  const team = await getTeam(teamId);
  const subscription = await getSubscription(team.subscriptionId);
  const totalSeats = calculateTotalSeats(subscription);
  const usedSeats = await countTeamMembers(teamId);

  if (usedSeats >= totalSeats) {
    throw new Error('No seats available. Please upgrade your plan.');
  }

  await sendInvitation(teamId, email);
}

Allow exceeding with a warning and grace period.

async function inviteUser(teamId: string, email: string) {
  const team = await getTeam(teamId);
  const { totalSeats, usedSeats } = await getSeatInfo(team);

  if (usedSeats >= totalSeats) {
    // Allow but flag for billing
    await flagOverage(teamId, usedSeats - totalSeats + 1);
    await notifyAdmin(team.adminEmail, 'You have exceeded your seat limit');
  }

  await sendInvitation(teamId, email);
}

Automatically add seats when limit is reached.

async function inviteUser(teamId: string, email: string) {
  const team = await getTeam(teamId);
  const { totalSeats, usedSeats, subscriptionId } = await getSeatInfo(team);

  if (usedSeats >= totalSeats) {
    // Automatically add a seat
    await client.subscriptions.changePlan(subscriptionId, {
      product_id: team.productId,
      quantity: 1,
      proration_billing_mode: 'prorated_immediately',
      addons: [{ addon_id: 'addon_seat', quantity: totalSeats - baseSeats + 1 }]
    });

    await notifyAdmin(team.adminEmail, 'A new seat was added to your plan');
  }

  await sendInvitation(teamId, email);
}

Advanced Patterns

Different Seat Types

Offer different seat types with different pricing:

Full Seats: $20/month - Full access to all features
View-Only Seats: $5/month - Read-only access
Guest Seats: $0/month - Limited external collaborator access

Implementation: Create separate add-ons for each seat type.

const session = await client.checkoutSessions.create({
  product_cart: [{
    product_id: 'prod_team_plan',
    quantity: 1,
    addons: [
      { addon_id: 'addon_full_seat', quantity: 10 },
      { addon_id: 'addon_viewer_seat', quantity: 25 },
      { addon_id: 'addon_guest_seat', quantity: 50 }
    ]
  }]
});

Annual Seat Discounts

Offer discounted annual seat pricing:

Monthly: $15/seat/month
Annual: $12/seat/month (20% savings)

Implementation: Create separate products for monthly and annual plans with different add-on prices.

Minimum Seat Requirements

Require a minimum number of seats for certain plans:

async function validateSeatCount(planId: string, seatCount: number) {
  const minimums = {
    'prod_starter': 1,
    'prod_team': 5,
    'prod_enterprise': 25
  };

  if (seatCount < minimums[planId]) {
    throw new Error(`${planId} requires at least ${minimums[planId]} seats`);
  }
}

Best Practices

Pricing Best Practices

Clear Communication: Show per-seat pricing prominently on your pricing page
Included Seats: Consider including a few seats in the base price to reduce friction
Volume Discounts: Offer lower per-seat rates for larger teams to win enterprise deals
Annual Incentives: Discount annual plans to improve cash flow and retention

Technical Best Practices

Cache Seat Counts: Cache subscription seat counts locally to avoid API calls on every request
Sync Regularly: Periodically sync your local seat count with Dodo Payments via API
Handle Failures: If a seat change fails, show clear error messages and retry options
Audit Trail: Log all seat changes for billing disputes and compliance

User Experience Best Practices

Real-Time Feedback: Show immediate cost impact when adjusting seats
Confirmation Steps: Require confirmation before billing changes
Proration Transparency: Clearly explain prorated charges before applying
Easy Downgrades: Don’t make it difficult to reduce seats (it builds trust)

Troubleshooting

Seat count mismatch between app and billing

Symptom: Your app shows a different seat count than the subscription.Causes:

Webhook not received or processed
Race condition during seat change
Cached data not updated

Solutions:

Implement webhook handlers for subscription.plan_changed
Add a “Sync with billing” button that fetches current subscription
Set cache TTL to ensure regular refresh

Proration charges unexpected

Symptom: Customer confused by mid-cycle charge amount.Causes:

Proration mode not communicated clearly
Customer didn’t see preview before confirming

Solutions:

Always use previewChangePlan before making changes
Show clear breakdown: “Adding X seats = $Y today (prorated for Z days)”
Document your proration policy in help center

Add-on not appearing in checkout

Symptom: Seat add-on not available during checkout.Causes:

Add-on not attached to product
Add-on archived or deleted
Currency mismatch between product and add-on

Solutions:

Verify add-on is attached in product settings
Check add-on status in Add-Ons dashboard
Ensure currencies match exactly

Cannot reduce seats below current usage

Symptom: Customer wants to reduce seats but has users assigned.Solutions:

Show which users must be removed before reducing seats
Implement a workflow: Remove users → Reduce seats
Consider a grace period before enforcing seat reduction

Seat-Based Pricing Tutorial

Complete implementation guide with code.

Add-ons

Understand the add-on system in depth.

Plan Changes & Proration

Handle subscription modifications.

Subscription Webhooks

Track subscription events.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Implementation Tutorial

Add-ons Documentation

Subscription Management

Webhooks

​What is Seat-Based Billing?

​Common Use Cases

​Benefits of Seat-Based Pricing

​How Seat-Based Billing Works in Dodo Payments

​Architecture Overview

​Key Components

​Pricing Strategies

​Strategy 1: Base + Per-Seat Add-on

​Strategy 2: Pure Per-Seat Pricing

​Strategy 3: Tiered Seat Pricing

​Strategy 4: Seat Bundles

​Setting Up Seat-Based Billing

​Step 1: Plan Your Pricing

​Step 2: Create the Seat Add-on

​Step 3: Create the Base Subscription

​Step 4: Attach Add-on to Product

​Managing Seats

​Adding Seats to New Subscriptions

​Changing Seat Count on Existing Subscriptions

​Removing Seats

​Removing All Additional Seats

​Proration for Seat Changes

​Proration Modes

​Proration Examples

​Preview Before Changing

​Tracking Seats with Webhooks

​Relevant Events

​Webhook Handler Example

​Enforcing Seat Limits

​Enforcement Strategies

​Advanced Patterns

​Different Seat Types

​Annual Seat Discounts

​Minimum Seat Requirements

​Best Practices

​Pricing Best Practices

​Technical Best Practices

​User Experience Best Practices

​Troubleshooting

​Related Documentation

Seat-Based Pricing Tutorial

Add-ons

Plan Changes & Proration

Subscription Webhooks

What is Seat-Based Billing?

Common Use Cases

Benefits of Seat-Based Pricing

How Seat-Based Billing Works in Dodo Payments

Architecture Overview

Key Components

Pricing Strategies

Strategy 1: Base + Per-Seat Add-on

Strategy 2: Pure Per-Seat Pricing

Strategy 3: Tiered Seat Pricing

Strategy 4: Seat Bundles

Setting Up Seat-Based Billing

Step 1: Plan Your Pricing

Step 2: Create the Seat Add-on

Step 3: Create the Base Subscription

Step 4: Attach Add-on to Product

Managing Seats

Adding Seats to New Subscriptions

Changing Seat Count on Existing Subscriptions

Removing Seats

Removing All Additional Seats

Proration for Seat Changes

Proration Modes

Proration Examples

Preview Before Changing

Tracking Seats with Webhooks

Relevant Events

Webhook Handler Example

Enforcing Seat Limits

Enforcement Strategies

Advanced Patterns

Different Seat Types

Annual Seat Discounts

Minimum Seat Requirements

Best Practices

Pricing Best Practices

Technical Best Practices

User Experience Best Practices

Troubleshooting

Related Documentation