Bill every successful outcome with outcome-based pricing

Overview

In outcome-based pricing, customers are billed when your product delivers a defined unit of value, rather than for time, seats, or raw consumption. This guide shows you how to build that model in Chargebee Billing: one metered feature per outcome type, a $99 monthly plan that includes 100 resolutions, and a metered addon per outcome type.

Throughout this guide, you configure one running example. An AI support agent charges for two outcomes:

At most one outcome is billed per conversation. The included resolutions are granted at the start of each monthly billing cycle. Resolutions past that allowance, and every procedure handoff, are rated and invoiced monthly.

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 pricing flow on a test site. You can test your billing setup in Chargebee's test site using Time Machine. Time Machine lets you simulate billing cycle progression, from subscription creation through the first invoice to later monthly cycles, 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 outcome events into Chargebee Billing

Start by streaming your product's outcomes into Chargebee Billing. For this example, a usage event is generated every time a conversation reaches a terminal state, and it includes outcome_quantity and outcome_type.

Chargebee's ingestion is schemaless. Chargebee Billing stores any additional properties you send alongside the required attributes and deduplicates repeated events.

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": "conv_123",
     "subscription_id": "{subscription_id}",
     "usage_timestamp": "1737612931000",
     "properties": {
          "outcome_type": "resolution",
          "outcome_quantity": 1
     }
}'

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": "conv_123",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612931000",
               "properties": {
                    "outcome_type": "resolution",
                    "outcome_quantity": 1
               }
          },
          {
               "deduplication_id": "conv_124",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612991000",
               "properties": {
                    "outcome_type": "procedure_handoff",
                    "outcome_quantity": 1
               }
          }
     ]
}'

2. Define the outcomes your product delivers

Now that usage is flowing, decide what feature(s) or product(s) you offer in the plan. In Chargebee Billing, you capture that unit by defining a metered feature. Create a metered feature for each of the outcome types to be billed. You set the aggregation rule and a filter on the feature, and from that point, Chargebee rolls up matching events against it.

For this example, create one metered feature per outcome type. Each feature uses Sum on outcome_quantity and a filter on outcome_type.

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="Resolutions" \
     -d feature_unit="resolution" \
     -d description="Number of successful resolutions." \
     -d query="SELECT SUM(outcome_quantity) from events WHERE outcome_type = 'resolution'" \
     -d "column_definitions[column_name][0]"="outcome_quantity" \
     -d "column_definitions[data_type][0]"="NUMBER" \
     -d "column_definitions[column_name][1]"="outcome_type" \
     -d "column_definitions[data_type][1]"="STRING"

3. Package your offerings into a plan

This step creates the monthly plan, sets its price, and defines how many resolutions are included each month.

3a. Create the plan

Create a Standard plan that carries the monthly 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="standard" \
     -d name="Standard" \
     -d type="PLAN" \
     -d item_family_id="{item_family_id}"

3b. Define the plan price point

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

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

3c. Grant the included resolutions

Link the Resolutions metered feature from Step 2 and set the included usage. Only resolutions are included with the plan, and linking is not needed for the procedure handoffs.

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[feature_id][0]"="resolutions" \
     -d "entitlements[entity_id][0]"="standard" \
     -d "entitlements[entity_type][0]"="PLAN" \
     -d "entitlements[value][0]"="100"

4. Price overages for the outcomes

A metered addon measures and rates a metered feature. Create one metered addon per outcome type. Resolution Overage bills every resolution after the 100 included resolutions are used. Procedure Handoff Outcome bills every procedure handoff, because that outcome has no included usage.

4a. Create the addons

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="resolution-overage" \
     -d name="Resolution Overage" \
     -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]"="resolutions" \
     -d "entitlements[entity_id][0]"="resolution-overage" \
     -d "entitlements[entity_type][0]"="ADDON" \
     -d "entitlements[value][0]"="unlimited"

4b. Define the addon price points

Create a monthly price point for each addon.

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}:\
     -d id="resolution-overage-USD-monthly" \
     -d item_id="resolution-overage" \
     -d name="Resolution Overage USD monthly" \
     -d pricing_model="PER_UNIT" \
     -d price=99 \
     -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 on Resolutions so you know when a customer approaches the included quota, and a Spends alert so you know when accrued outcome charges reach an amount you choose.

A Usages alert triggers when a subscription's usage of a metered feature exceeds a percentage of included usage. Procedure handoffs are billed from the first unit and have no included usage. Watch those charges with a Spends alert. A Spends alert triggers when usage charges from metered addons (overage charges) exceed an amount you set.

See Usage Alerts and Setting up Alerts. Configure a webhook endpoint and include the alert_status_changed event before you rely on the alerts. See Webhook settings.

Create a Usages alert

On Standard, 80 percent of included usage is 80 resolutions.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="usage_exceeded" \
     -d name="Resolutions 80 percent" \
     -d description="Notify when resolutions cross 80 percent of included usage" \
     -d metered_feature_id="resolutions" \
     -d "threshold[mode]"="percentage" \
     -d "threshold[value]"=80

Create a Spends alert

This example fires when accrued outcome charges exceed $100.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="spend_exceeded" \
     -d name="Outcome spend 100" \
     -d description="Notify when accrued outcome charges reach 100 USD" \
     -d currency_code="USD" \
     -d "threshold[mode]"="absolute" \
     -d "threshold[value]"=100

Take action when the threshold is reached

When resolutions exceed the percentage you set, or when accrued outcome charges exceed the amount you set, the alert status changes from within_limit to in_alarm. Chargebee sends an alert_status_changed webhook. Use that webhook to email the customer, show an upgrade prompt, or start another workflow. Chargebee Billing records the outcomes and does not enforce a stop.

For a Usages alert, when usage resets at the start of a new billing cycle, the alert status returns to within_limit.

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 Standard plan, and attach both metered addons so resolutions past the allowance and procedure handoffs can be rated 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]"="standard-USD-monthly" \
     -d "subscription_items[item_price_id][1]"="resolution-overage-USD-monthly" \
     -d "subscription_items[item_price_id][2]"="procedure-handoff-outcome-USD-monthly"

curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/entitlement_overrides \
     -X POST \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlement_overrides[feature_id][0]"="resolutions" \
     -d "entitlement_overrides[value][0]"="150"

The active subscription looks like this:

7. Track usage against your subscriptions and share with customers

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

Monitor usage during the current period

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

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

Handle outcome reversals

An outcome can be invalidated after it was delivered. In this example, a customer returns to a resolved conversation, and the original resolution should come out of the billable count.

If a later reversal is accepted, its timestamp applies only to the billing period that contains it. That reversal does not reduce a closed invoice from an earlier period. Correcting a closed invoice requires the applicable credit note workflow, or voiding the invoice and regenerating it. A compensating event affects only a later invoice.

Whether the ingest API and a SUM meter accept a negative outcome_quantity is [unverified]. If that value is accepted, send a second usage event with outcome_quantity set to -1, a new deduplication ID, and usage_timestamp set to the current time. A SUM aggregation would then include that event only in the billing period that contains the reversal timestamp.

The reversal must use a new deduplication ID. If you reuse conv_123, Chargebee Billing discards the reversal as a duplicate.

Manage outcome invoices

At the end of each monthly billing period, Chargebee Billing creates the usage invoice for resolutions past the allowance and for procedure handoffs in a Pending state. While an invoice is pending, you can still ingest usage events dated within the accepted backdating window, including reversal events, and they are included in the final charge. Pending invoices do not trigger payment collection.

You manage how pending 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, or send a compensating event so the correction lands on the next invoice.

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

Summary

This guide showed you how to turn outcome events into one metered feature per outcome type, grant 100 included resolutions each month on a $99 plan, and rate resolutions past that allowance and every procedure handoff with monthly metered addons. You can monitor usage and validate the cycle with Time Machine.

The same pattern works for any product that can define a discrete unit of value and emit one event per unit.