Seat-Based Billing - Dodo Payments Documentation

Seat-based billing charges customers based on the number of users on their account. Dodo Payments implements it using the add-on system: a base subscription product plus a per-seat add-on whose quantity represents the seat count.

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-basierte Abrechnung berechnet Kunden abhängig von der Anzahl der Nutzer, die auf Ihr Produkt zugreifen. Statt einer Pauschalgebühr steigt der Preis mit der Teamgröße.

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

Für Ihr Unternehmen:

Der Umsatz steigt, wenn Ihre Kunden wachsen
Kunden können ihre Kosten planbar budgetieren
Klarer Upgrade-Pfad vom Einzelkunden über das Team bis zum Unternehmen
Höherer Customer Lifetime Value, wenn Teams wachsen

Für Ihre Kunden:

Sie zahlen nur für die Nutzer, die sie tatsächlich haben
Kosten lassen sich einfach verstehen und prognostizieren
Nutzer können nach Bedarf hinzugefügt oder entfernt werden
Faire Preise, die der Teamgröße entsprechen

How It Works

Dodo Payments implements seat-based billing using the Add-ons system. A seat-based subscription has two parts:

Komponente	Beschreibung	Beispiel
Basisprodukt	Der Abonnementtarif	”Team Plan” — $50/Monat
Seat-Zusatz	Eine Gebühr pro Einheit für jeden Seat	”Extra Seat” — $10/Monat pro Seat

The customer’s monthly total is:

Total = Base price + (Seat add-on price × seat quantity)

Beispiel: 8 zusätzliche Seats bei einem Team Plan

Base plan:  $50/month
Seats:      8 × $10 = $80/month
────────────────────────────────
Total:      $130/month

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.

Team Plan: $49/month (includes 5 seats)
Extra seats: $10/month each
8 total seats = $49 + (3 × $10) = $79/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.

Per Seat: $12/month
5 users  = 5 × $12  = $60/month
50 users = 50 × $12 = $600/month

Implementierung: Setzen Sie den Preis des Basistarifs auf $0 und verwenden Sie ausschließlich den Seat-Zusatz. Am besten geeignet für: Einfache, transparente Preise.

Strategy 3: Tiered Seat Pricing

Different base plans with different per-seat rates.

Starter:     $0/month   + $15/seat
Pro:         $99/month  + $10/seat
Enterprise:  $499/month + $7/seat

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.

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

Legen Sie fest, was im Basisabonnement enthalten ist:

Basisp reis (kann bei reiner Seat-Abrechnung $0 betragen)
Anzahl der enthaltenen Seats
In dieser Stufe verfügbare Funktionen

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:

Feld	Wert	Hinweise
Name	”Additional Seat” oder “Team Member”	Klarer, benutzerfreundlicher Name
Description	”Add another team member to your workspace”	Erklären Sie, was Kunden erhalten
Price	Ihr Preis pro Seat	z. B. $10.00
Currency	Entspricht Ihrem Basisprodukt	Muss dieselbe Währung sein
Tax Category	Wie beim Basisprodukt	Gewährleistet eine konsistente Steuerbehandlung

Verwenden Sie beschreibende Namen für Zusätze, die auf Rechnungen verständlich sind. “Additional Team Seat” ist für Kunden, die ihre Rechnungen prüfen, klarer als “Seat Add-on”.

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: 'pdt_team_plan',
    quantity: 1,
    addons: [{
      addon_id: 'adn_YOUR_SEAT_ADDON',
      quantity: 8  // 8 additional seats
    }]
  }],
  customer: { email: 'admin@company.com' },
  return_url: 'https://yourapp.com/success'
});

Changing Seat Count on Existing Subscriptions

Use the Change Plan API to adjust seats. The addons array sets the new total seat count (not the delta).

// Currently 3 seats → change to 8 seats
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [{
    addon_id: 'adn_YOUR_SEAT_ADDON',
    quantity: 8  // new total, not +5
  }]
});

Removing Seats

To reduce seat count, specify the lower quantity:

// Currently 8 seats → reduce to 3 seats
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: [{
    addon_id: 'adn_YOUR_SEAT_ADDON',
    quantity: 3  // new total
  }]
});

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: 'pdt_team_plan',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  addons: []  // removes all add-ons
});

Proration for Seat Changes

When a seat change is applied mid-cycle, Dodo Payments calculates the immediate charge in three steps:

Credit   →  a portion of the OLD plan's price (base + all add-ons)
Charge   →  a FULL cycle of the NEW plan's price
Net      =  Charge − Credit

The credit amount depends on the proration mode you choose. The charge is always a full cycle.

Die Gebühr gilt immer für einen vollständigen Abrechnungszyklus. Nur das Guthaben variiert je nach Modus. Deshalb entspricht der berechnete Betrag nur selten “neue Seats × Preis × verbleibende Tage”.Bei prorated_immediately sinkt das Guthaben im Verlauf des Zyklus, sodass dieselbe Seat-Änderung umso mehr kostet, je später sie vorgenommen wird. Bei difference_immediately und full_immediately hängt das Guthaben nicht vom Zeitpunkt ab, daher kosten diese beiden Modi an jedem Tag des Zyklus gleich viel.

How Each Mode Credits

Mode	Credit (old plan)	Charge (new plan)	Billing cycle
`prorated_immediately`	Remaining time only (time left ÷ cycle length)	Full cycle	Resets to today
`difference_immediately`	The whole old plan	Full cycle	Resets to today
`full_immediately`	None (0%)	Full cycle	Resets to today
`do_not_bill`	Nothing credited, nothing charged	Not charged now — seats active immediately	Unchanged

Bei difference_immediately zahlt der Kunde nur die Differenz zwischen dem Preis des alten und des neuen Tarifs. Daher stammt der Name, und deshalb ist der Betrag unabhängig davon gleich, wann im Zyklus die Änderung vorgenommen wird. If the credit is larger than the new cycle charge, the difference is held as subscription-scoped credit and applied automatically to future renewals.

prorated_immediately, difference_immediately und full_immediately setzen den Abrechnungszyklus auf das Änderungsdatum zurück. Die nächste Verlängerung wird auf den Tag verankert, an dem die Seat-Änderung angewendet wird. Nur do_not_bill behält das ursprüngliche Verlängerungsdatum bei (die neue Seat-Anzahl wird bei der nächsten Verlängerung vollständig berechnet, ohne Gebühr zum Zeitpunkt der Änderung).

do_not_bill applies the seat change immediately, not at renewal. The new seat count takes effect as soon as the call succeeds, but nothing is charged until the next renewal.Beim Hinzufügen von Seats kann der Kunde sie für den Rest des aktuellen Zyklus kostenlos nutzen. Wenn am ersten Tag eines 30-tägigen Zyklus 5 Seats zu je $10 hinzugefügt werden, erhält der Kunde 5 Seats für 29 Tage kostenlos; der höhere Betrag wird erstmals am ursprünglichen Verlängerungsdatum berechnet.Beim Entfernen von Seats gilt das Gegenteil: Die Seats werden sofort entzogen, und für den bereits bezahlten Teil des Zyklus wird kein Guthaben gewährt.Use do_not_bill when that is what you intend, such as a courtesy upgrade or a sales-agreed trial of extra seats.

Worked Example: Adding 5 Seats

One scenario run through all four modes, so the numbers are directly comparable.

Plan:      $50/month base + $10/seat add-on
Current:   $50 + 3 × $10 = $80/month
New:       $50 + 8 × $10 = $130/month
Timing:    Day 15 of a 30-day cycle (50% remaining)

Modus	Guthaben	Gebühr	Netto heute	Nächste Verlängerung
`prorated_immediately`	−$40.00 (50 % × $80)	+$130.00	$90.00	$130/Monat ab heute
`difference_immediately`	−$80.00 (der gesamte alte Tarif)	+$130.00	$50.00	$130/Monat ab heute
`full_immediately`	$0.00	+$130.00	$130.00	$130/Monat ab heute
`do_not_bill`	—	—	$0.00	$130/Monat am ursprünglichen Verlängerungsdatum

In allen drei sofort wirksamen Modi erhält der Kunde im Austausch für die heutige Zahlung einen vollständigen neuen Monat für $130.

Why Timing Matters for `prorated_immediately`

The same change costs more the later in the cycle it is made, because less of the current cycle is left to credit back.

Current: $80/month → New: $130/month

Zeitpunkt	Verbleibend	Guthaben	Gebühr	Netto heute
Tag 3 von 30	90 %	−$72.00	+$130.00	$58.00
Tag 15 von 30	50 %	−$40.00	+$130.00	$90.00
Tag 27 von 30	10 %	−$8.00	+$130.00	$122.00

The customer receives a full new month in every row. Only the split between “already paid for” and “paying now” changes. Damit eine Seat-Änderung unabhängig vom Zeitpunkt immer gleich viel kostet, verwenden Sie difference_immediately.

Worked Example: The “Surprising Charge”

This is the case that most often surprises merchants. Adding a small seat add-on late in the cycle can produce a charge much larger than the add-on’s price.

Plan:      $50/month base, no add-ons
Change:    add 1 seat at $10/month
Timing:    Day 27 of a 30-day cycle (10% remaining)

Modus	Guthaben	Gebühr	Netto heute
`prorated_immediately`	−$5.00 (10 % × $50)	+$60.00	$55.00
`difference_immediately`	−$50.00 (der gesamte alte Tarif)	+$60.00	$10.00
`full_immediately`	$0.00	+$60.00	$60.00
`do_not_bill`	—	—	$0.00

Das Hinzufügen eines Seats für $10/Monat kostet mit prorated_immediately $55.00. Dem Kunden wird ein vollständiger neuer Monat für $60 berechnet und das im alten Monat verbleibende Guthaben von $5 gutgeschrieben; außerdem wird das Verlängerungsdatum zurückgesetzt. Damit kleine untermonatige Erweiterungen genau den Seat-Preis und nichts weiter kosten, verwenden Sie difference_immediately.

Worked Example: Removing Seats (Downgrade)

When the new plan costs less than the credit, the excess is held as subscription credit and applied automatically to future renewals of this subscription. It is not added to the Customer Wallet and is not a credit entitlement.

Current:   $50 base + 8 × $10 seats = $130/month
New:       $50 base + 2 × $10 seats = $70/month
Timing:    Day 6 of a 30-day cycle (80% remaining)
Mode:      prorated_immediately

Credit for unused time on the current cycle (base plus all add-ons):
  = $130 × 80%
  = $104.00 credit

Charge for a full cycle at the new seat count:
  = $50 + (2 × $10)
  = $70.00

Net = $70.00 − $104.00 = −$34.00

→ $0 charged today
→ $34.00 held as subscription credit (applied to future renewals)
→ Billing cycle resets; next renewal is $70/month

Das Guthaben umfasst das gesamte Abonnement, den Basistarif und alle Zusätze, nicht nur die Seats, die entfernt werden.

Reading the Preview Response

previewChangePlan returns the exact line items that will be billed. Each line item has a proration_factor:

`proration_factor`	Meaning
Negative (e.g. `−0.50`)	Credit — fraction of the old plan being refunded
`1`	Charge — a full new billing cycle
`0`	No charge / no credit for this line

{
  "immediate_charge": {
    "summary": {
      "settlement_amount": 9000,
      "settlement_currency": "USD"
    },
    "line_items": [
      {
        "type": "subscription",
        "unit_price": 5000,
        "quantity": 1,
        "proration_factor": -0.50
      },
      {
        "type": "addon",
        "unit_price": 1000,
        "quantity": 3,
        "proration_factor": -0.50
      },
      {
        "type": "subscription",
        "unit_price": 5000,
        "quantity": 1,
        "proration_factor": 1
      },
      {
        "type": "addon",
        "unit_price": 1000,
        "quantity": 8,
        "proration_factor": 1
      }
    ]
  }
}

Das bedeutet: $50 Basistarif und 3 × $10 Zusatz werden zu 50 % gutgeschrieben, ein vollständiger Basistarif von $50 wird berechnet und 8 × $10 Zusatz werden berechnet. Guthaben = $40, Gebühr = $130, Netto = $90.

Proration is calculated to the second based on the exact time of the change, not rounded to the nearest day. The worked examples above use round day-boundary numbers for clarity.

Choosing a proration mode for seat changes

difference_immediately — Der Kunde zahlt die Preisdifferenz, unabhängig davon, wann die Änderung vorgenommen wird. Am planbarsten für Teams, die ihre Seat-Anzahl häufig anpassen, und am einfachsten in Ihrer Benutzeroberfläche zu erklären.
prorated_immediately — Dem Kunden wird nur die verbleibende Zeit des aktuellen Zyklus gutgeschrieben. Je später im Zyklus die Änderung vorgenommen wird, desto höher sind die Kosten.
full_immediately — Der Kunde zahlt für einen vollständigen neuen Zyklus, ohne Guthaben für ungenutzte Zeit.
do_not_bill — Die Seat-Änderung wird sofort wirksam, aber jetzt wird nichts berechnet. Hinzugefügte Seats sind bis zur nächsten Verlängerung kostenlos; entfernte Seats werden ohne Guthaben entzogen. Das Verlängerungsdatum bleibt erhalten, und ab dieser Verlängerung wird die neue Seat-Anzahl vollständig berechnet. Der einzige Modus, der den Abrechnungszyklus nicht zurücksetzt.

Seats granted through do_not_bill are not credited on a later plan change, because they were never billed. If you add 5 seats with do_not_bill and then change to 3 seats, the customer is billed for 3 seats in full with no credit for the 5 they were holding.

Always call previewChangePlan and show the returned amount before confirming. See the Proration Guide for detailed comparisons.

Preview Before Changing

Always preview proration before making changes:

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

console.log('Charge today:', preview.immediate_charge.summary.settlement_amount);
console.log('Currency:', preview.immediate_charge.summary.settlement_currency);
// Show customer: "Adding 5 seats will cost $90.00 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 addonSeats = event.data.addons?.reduce(
        (total, addon) => total + addon.quantity, 0
      ) || 0;
      await provisionSeats(event.data.customer.customer_id, addonSeats);
      break;
    }

    case 'subscription.plan_changed': {
      // Seats changed - update access
      const newSeats = event.data.addons?.reduce(
        (total, addon) => total + addon.quantity, 0
      ) || 0;
      await updateSeatCount(event.data.subscription_id, newSeats);
      break;
    }

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

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

The addons array in the webhook payload contains the current addon quantities. Sum them to get the total seat count. If your base plan includes seats (e.g. 5 included), add that to the addon total in your application logic.

Enforcing Seat Limits

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

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);
  // seatAddonQuantity is the current quantity of the seat add-on on the subscription
  const { totalSeats, usedSeats, subscriptionId, seatAddonQuantity } = 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: 'adn_YOUR_SEAT_ADDON', quantity: seatAddonQuantity + 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: 'pdt_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 = {
    'pdt_starter': 1,
    'pdt_team': 5,
    'pdt_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

Feedback in Echtzeit: Zeigen Sie die Kostenauswirkungen sofort an, wenn Seats angepasst werden
Bestätigungsschritte: Fordern Sie vor Änderungen der Abrechnung eine Bestätigung an
Transparenz bei anteiligen Abrechnungen: Erklären Sie anteilige Gebühren klar, bevor Sie sie anwenden
Einfache Downgrades: Erschweren Sie die Reduzierung von Seats nicht (das schafft Vertrauen)

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

Unexpected mid-cycle charge amount

Symptom: Customer confused by mid-cycle charge amount.Cause: Using prorated_immediately late in the billing cycle (see The Surprising Charge example above).Lösungen:

Verwenden Sie vor Änderungen immer previewChangePlan
Zeigen Sie eine klare Aufschlüsselung: “Das Hinzufügen von X Seats kostet heute $Y”
Wechseln Sie zu difference_immediately, wenn die Gebühr immer der Preisdifferenz entsprechen soll

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.

Implementation Tutorial

Add-ons Documentation

Subscription Management

Webhooks

​What is Seat-Based Billing?

​Common Use Cases

​Benefits of Seat-Based Pricing

​How It Works

​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

​How Each Mode Credits

​Worked Example: Adding 5 Seats

​Why Timing Matters for prorated_immediately

​Worked Example: The “Surprising Charge”

​Worked Example: Removing Seats (Downgrade)

​Reading the Preview Response

​Preview Before Changing

​Tracking Seats with Webhooks

​Relevant Events

​Webhook Handler Example

​Enforcing Seat Limits

​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 It Works

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

How Each Mode Credits

Worked Example: Adding 5 Seats

Why Timing Matters for `prorated_immediately`

Worked Example: The “Surprising Charge”

Worked Example: Removing Seats (Downgrade)

Reading the Preview Response

Preview Before Changing

Tracking Seats with Webhooks

Relevant Events

Webhook Handler Example

Enforcing Seat Limits

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