Bill per seat with included usage per seat and monthly overages

Overview

Seat-based pricing charges customers for the number of users who have access to your product. Many products pair the per-seat fee with an allowance of included usage, so the allowance grows as the customer adds seats. Any usage beyond the allowance still needs to be invoiced as it happens, so billing stays aligned with consumption. This guide shows you how to build that hybrid model in Chargebee Billing: a monthly per-seat plan whose included usage is defined once at the plan level and multiplied by the number of seats on the subscription, paired with monthly metered addons that bill every unit consumed beyond the total included usage.

Throughout this guide, you configure the model for a single running example. John Doe signs up for an AI workspace product on the Team plan: $20 per seat per month, with 10,000 API requests and 5 GB storage included per seat each month. If the team consumes more than its included total in a month, the excess is invoiced monthly at $0.02 per API request and $1 per GB of storage. John Doe buys 10 seats, so the subscription is billed $200 per month and is granted 100,000 API requests and 50 GB storage.

How this billing model works

The illustration below explains how this billing model works:

Before you start

If you don't already have a Chargebee Billing account, click here to sign up.

Advanced Usage-Based Billing is enabled by default for new Chargebee Billing sites. If you are an existing user, enable it before you build the model.

Validate before go-live

Before enabling this on a live site, validate the full monthly cycle on a test site, including a mid-term change in seats. You can test your billing setup in Chargebee's test site using Time Machine. Time Machine lets you simulate billing cycle progression, from the initial invoice through monthly overages to renewal, without waiting for real calendar time.

When you are ready to go live, copy the configuration and Product Catalog from the test site to the live site with Transfer Configurations. To transfer customer, subscription, or invoices data, you can import them on your live site.

Implementation steps

Follow these steps in order. Each step shows how to do the task in the Chargebee Billing app and with the API.

1. Send usage into Chargebee Billing

Start by streaming your product's usage into Chargebee Billing before you've decided what to charge for. For this example, a usage event is generated for API requests, and it includes an api_requests property. Another usage event reports how much storage the workspace is using, and it includes a storage_gb property. For your business, this could be a file upload, a message sent, a workflow run, and so on.

Chargebee's ingestion is schemaless. While this example uses API requests and storage as the value metrics, you can track usage for additional parameters as required for your business. You can start sending raw usage before finalizing the per-seat quotas or overage rates. Track adoption patterns over time, then use those insights to define the metered features, included usage per seat, and overage pricing.

You can send usage in one of the following ways, based on how your product emits usage:

curl  https://{site}.ingest.chargebee.com/api/v2/usage_events \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "deduplication_id": "usage-api-0001",
     "subscription_id": "{subscription_id}",
     "usage_timestamp": "1737612931000",
     "properties": {
          "api_requests": 12,
          "request_id": "req_1001",
          "user_id": "user_01"
     }
     }'

curl  https://{site}.ingest.chargebee.com/api/v2/batch/usage_events \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "events": [
          {
               "deduplication_id": "usage-api-0001",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612931000",
               "properties": {
                    "api_requests": 12,
                    "user_id": "user_01"
               }
          },
          {
               "deduplication_id": "usage-storage-0001",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612991000",
               "properties": {
                    "storage_gb": 41.5
               }
          }
     ]
     }'

2. Define the units of value your product delivers

Now that usage is flowing, decide what you'll actually charge for beyond the seat fee: the units of value your product delivers. For this example, a usage event records API requests and storage in GB. For your business, this could be a file upload, a message sent, an image generated, and so on.

A metered feature tells Chargebee how to aggregate your raw events into a single billable number for each period. You set the aggregation rule on the feature, and from that point Chargebee rolls up matching events against it.

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="API Requests" \
     -d feature_unit="api_request" \
     -d description="Number of API requests consumable." \
     -d query="SELECT SUM(api_requests) from events" \
     -d "column_definitions[column_name][0]"="api_requests" \
     -d "column_definitions[data_type][0]"="NUMBER"

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="Storage" \
     -d feature_unit="gb" \
     -d description="Storage consumable, in gigabytes." \
     -d query="SELECT MAX(storage_gb) from events" \
     -d "column_definitions[column_name][0]"="storage_gb" \
     -d "column_definitions[data_type][0]"="NUMBER"

3. Package your offerings into a plan

This step establishes the per-seat plan, sets its price per seat, and defines how many API requests and how much storage are included for each seat.

3a. Create the plan

Create a Team plan that carries the per-seat platform fee, and link pricing to the plan in the next step.

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="team" \
     -d name="Team" \
     -d type="PLAN" \
     -d item_family_id="{item_family_id}"

3b. Define the plan price point

Once the plan is saved, create a per-seat price point for it.

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}:\
     -d id="team-USD-monthly" \
     -d item_id="team" \
     -d name="Team USD monthly" \
     -d pricing_model="PER_UNIT" \
     -d price=2000 \
     -d currency_code="USD" \
     -d period_unit="MONTH" \
     -d period=1

3c. Grant features and define included usage

Link the API Requests and Storage metered features you created in Step 2 and set the included usage for each. Define the included usage for a single seat. Chargebee Billing multiplies each plan-level entitlement by the number of seats on the subscription.

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[feature_id][0]"="api-requests" \
     -d "entitlements[entity_id][0]"="team" \
     -d "entitlements[entity_type][0]"="PLAN" \
     -d "entitlements[value][0]"="10000" \
     -d "entitlements[feature_id][1]"="storage" \
     -d "entitlements[entity_id][1]"="team" \
     -d "entitlements[entity_type][1]"="PLAN" \
     -d "entitlements[value][1]"="5"

4. Define how to measure overages

Metered addons are catalog items that let you measure and rate metered features beyond the included usage granted through the plan. In this case, one addon bills customers for every API request made after the total included API requests across all seats is exhausted, and another bills every GB of storage used beyond the total included storage.

4a. Create the addons

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="on-demand-api-requests" \
     -d name="On-demand API Requests" \
     -d type="ADDON" \
     -d item_family_id="{item_family_id}" \
     -d metered=true

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[feature_id][0]"="api-requests" \
     -d "entitlements[entity_id][0]"="on-demand-api-requests" \
     -d "entitlements[entity_type][0]"="ADDON" \
     -d "entitlements[value][0]"="unlimited" \
     -d "entitlements[feature_id][1]"="storage" \
     -d "entitlements[entity_id][1]"="on-demand-storage" \
     -d "entitlements[entity_type][1]"="ADDON" \
     -d "entitlements[value][1]"="unlimited"

4b. Define the addon price points

Once the addons are created, create a monthly price point for each of them.

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}:\
     -d id="on-demand-api-requests-USD-monthly" \
     -d item_id="on-demand-api-requests" \
     -d name="On-demand API Requests USD monthly" \
     -d pricing_model="PER_UNIT" \
     -d price=2 \
     -d currency_code="USD" \
     -d period_unit="MONTH" \
     -d period=1

5. Be notified on usage and spends and take desired action

Use a Usages alert to watch API requests and storage against the subscription's total included monthly usage, and a Spends alert to watch accrued overage charges before the monthly invoice is generated.

Create a Usages alert

A Usages alert monitors a metered feature against a percentage of the subscription's included usage. Set alerts at 75% to warn the account admin before overages begin and 100% to notify them when the included quota is exhausted.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}: \
     -d type="usage_exceeded" \
     -d name="API requests 75 percent" \
     -d description="Notify when API requests exceed 75 percent of included monthly usage" \
     -d metered_feature_id="api-requests" \
     -d "threshold[mode]"="percentage" \
     -d "threshold[value]"=75 \
     -d "filter_conditions[field][0]"="plan_price_id" \
     -d "filter_conditions[operator][0]"="equals" \
     -d "filter_conditions[value][0]"="team-USD-monthly"

Create a Spends alert

A Spends alert monitors accrued charges for usage beyond the included entitlements. In this model, it watches the combined overage spend from On-demand API Requests at $0.02 per excess API request and On-demand Storage at $1 per excess GB.

For example, set a $50 threshold to notify the account admin when monthly overage spend exceeds that amount. This is a notification threshold, not a spending cap: both addons continue to bill overages unless your product takes action.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}: \
     -d type="spend_exceeded" \
     -d name="Team monthly overage spend 50 USD" \
     -d description="Notify when combined API request and storage overage spend exceeds 50 USD" \
     -d currency_code="USD" \
     -d "threshold[mode]"="absolute" \
     -d "threshold[value]"=50 \
     -d "filter_conditions[field][0]"="plan_price_id" \
     -d "filter_conditions[operator][0]"="equals" \
     -d "filter_conditions[value][0]"="team-USD-monthly"

Take action when a threshold is crossed

When an alert's threshold is exceeded, its status changes from within_limit to in_alarm, and Chargebee sends an alert_status_changed webhook. Use your webhook handler to route the notification to email, an in-app prompt, Slack, your CRM, or another workflow:

• 75% usage: Warn the account admin that API requests or storage are approaching the included monthly allowance, and offer a seat increase if the team needs more users and included usage.
• 100% usage: Notify the admin that the feature's included allowance is exhausted and further usage is charged at the corresponding overage rate.
• $50 overage spend: Notify the admin of accrued overage charges and prompt them to review consumption or adjust their subscription.

If you want to pause API requests or restrict additional storage, enforce that behavior in your product. For usage alerts, the status returns to within_limit when usage resets at the start of the next monthly billing cycle.

6. Create the customer and subscription

With the catalog in place, create the customer and their subscription. A customer record must exist before a subscription can be created. You can create it first, or create both together in the same flow. Create the subscription for John Doe on the Team plan with a quantity of 10 seats, and attach both metered addons so overages can be invoiced monthly.

curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d email="jdoe@example.com"

curl  https://{site}.chargebee.com/api/v2/customers/{customer_id}/subscription_for_items \
     -u {site_api_key}:\
     -d "subscription_items[item_price_id][0]"="team-USD-monthly" \
     -d "subscription_items[quantity][0]"=10 \
     -d "subscription_items[item_price_id][1]"="on-demand-api-requests-USD-monthly" \
     -d "subscription_items[item_price_id][2]"="on-demand-storage-USD-monthly"

Your active subscription looks like this:

7. Track usage against your subscriptions and share with customers

Use the following options to monitor usage, review billed consumption, and answer customer questions about their invoice.

Monitor usage during the current term

curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usage_summary \
     -G \
     -u {site_api_key}: \
     --data-urlencode feature_id="api-requests"

curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usage_charges \
     -u {site_api_key}:

Review usage after invoicing and share details with customers

Related use cases

Manage overage invoices

At the end of each monthly billing period, Chargebee Billing creates the overage invoice in a Pending state. While an invoice is pending, you can still ingest usage events dated within the accepted backdating window, and they're included in the final charge. Pending invoices don't trigger payment collection.

You manage how pending overage invoices close under Settings > Configure Chargebee > Billing LogIQ > Usage Based Billing. Two behaviors are available:

• Manual close. Review all usage, then close the invoice yourself.
• Auto-close. Chargebee Billing closes the invoice automatically at a time you define.

Once an invoice is closed, no further usage can be added to it, and payment collection begins. If you need to correct a closed invoice, void it and regenerate it with the updated usage.

See Actions for pending invoices, the Invoices API, and the Credit Notes API.

Offer a trial period

On a per-seat plan with included usage, you can offer a trial without a usage cap or with a fixed quota.

To offer a trial without a usage cap, open the plan price point, select This plan has a trial period, and enter the trial duration. Chargebee Billing does not bill usage during the trial. Billing for usage starts when the trial ends. See Trial Management.

To offer a trial with a fixed quota, create a separate trial plan for the required duration and define custom entitlements for that period. The subscription starts on this trial plan. At the end of one billing cycle, update the subscription to the Team monthly plan. You can schedule that change with Subscription Ramps.

Add or remove seats mid-term

Teams grow and shrink during the month. When a plan's quantity changes mid-term, Chargebee Billing handles both the charge and the included usage:

Example

John Doe's team adds 5 seats mid-month, going from 10 to 15 seats. The included usage for the billing period becomes 150,000 API requests (10,000 × 15) and 75 GB storage (5 GB × 15). A team that had made 112,000 API requests and used 56 GB is now within both quotas, so no overage is charged for the month. Because entitlements scale for the entire billing period, removing seats works the same way in reverse: a team that reduces seats after heavy usage may move into overage.

curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/update_for_items \
     -u {site_api_key}:\
     -d "subscription_items[item_price_id][0]"="team-USD-monthly" \
     -d "subscription_items[quantity][0]"=15

To schedule a seat change for the next renewal instead, use Subscription Ramps. For the full proration and entitlement behavior, see Mid-term subscription changes.

FAQs

How do I combine seat-based pricing with prepaid credits?

Keep the Team plan's per-seat price and use a prepaid credit grant instead of separate included-usage quotas for the features that should consume credits. Configure a credit unit, such as AI Credits, and a monthly grant on the plan price, including rollover settings. Set a credit rate on each eligible metered feature so usage draws down the subscription's credit balance. To bill after credits run out, attach a metered addon configured to bill overage for that credit unit, rather than the feature-overage addons used in this guide.

What if included usage should not multiply with the number of seats?

Keep the per-seat Team plan for the seat fee, but grant the fixed allowance through a separate non-metered addon instead of the plan. Create a $0 monthly flat-fee addon, link it to API Requests and Storage, and define included usage of 10,000 API requests and 5 GB. Attach the addon once to the subscription and remove the corresponding plan-level entitlements so the allowances are not combined.

The subscription then receives the same 10,000 API requests and 5 GB each month, regardless of its seat count. Keep both metered overage addons attached to bill consumption beyond these fixed allowances at the rates defined in this guide.

Summary

This guide showed you how to:

• Turn raw usage into metered features for API requests and storage, then configure a per-seat plan whose included usage is multiplied by the number of seats, and monthly addons for overages.
• Create the subscription with a seat quantity, monitor usage and alerts, manage seat changes, and validate the complete cycle with Time Machine.