# Measured add-on use case

Here we will measure the total tokens consumed by a customer and bill them on a per unit basis of $0.10/token, our UOM will be token and we'll create a new rate plan for an existing product that includes this new charge along with the products existing $100/month per seat. We'll also include 1000 tokens at no extra cost each month.

Returning to our [pre-launch checklist](/docs/get-started/tutorials/ai-monetization/ai-monetization-overview#ai-monetization-pre-launch-checklist):

* Is mediation enabled? Yes
* A charge model? We will use a recurring monthly charge combined with a usage charge, pricing above. No commitments or pre-pays in this example, this will be pay as you go.
* Variable vs recurring? Both
* Pay in advance or in arrears? Arrears
* The unit of measure(s) involved? Token
* Is Zuora Mediation needed? And what transformations are needed to convert the source event data to a canonical Zuora Usage Record? Yes, we'll need to deduplicate, filter, calculate quantity based on values in three fields in the event record, map the incoming tenant_id value as the Zuora Billing Account Number, and add a UOM value to every event. We're about to show you how to do all this.


As a learning exercise it is better to create your first one or two meters by hand in the Zuora UI so you can learn how they work.

Before proceeding create the Token Unit of Measure, the product rate plan and billing account and subscription as described in [Basics for all examples](/docs/get-started/tutorials/ai-monetization/basics-for-all-examples). Edit the [llm_usage.csv](/assets/llm_usage.21181400708c13a3b3bac62672b0a5a0ff4120a0456b371d6bef92a0bdbaf95b.b4f54b07.csv) file with the correct AccountNumber in the 'tenant_id' column.

## Create our custom meter

Review how to build a meter for this use case in the [Building Meters video](/assets/zuora-mediation-building-meters.88b0276d7e1b52ff0b04ff5f56c07a59c652736171435297f87bd599d4848e2c.b4f54b07.mp4).

Previously we showed how to [create the UOM](/docs/get-started/tutorials/ai-monetization/basics-for-all-examples#create-a-new-unit-of-measure) and how to [create the product and product rate plan](/docs/get-started/tutorials/ai-monetization/basics-for-all-examples#create-a-new-product-product-rate-plan-and-product-rate-plan-charge). We won't cover how to create [the billing account, subscription and rate plan](/docs/get-started/tutorials/ai-monetization/basics-for-all-examples#create-a-new-product-product-rate-plan-and-product-rate-plan-charge).

We **strongly recommend** watching the [video](/assets/zuora-mediation-building-meters.88b0276d7e1b52ff0b04ff5f56c07a59c652736171435297f87bd599d4848e2c.b4f54b07.mp4) first, it will center you much more quickly than working the UI by yourself. Once your meter is built and running, there's a short video on [monitoring your meters](/assets/zuora-mediation-monitoring-meters.b39a2d03d4a30fe7b6311f2548b478bf8385a228349db4fa5c6ecf696c8b395f.b4f54b07.mp4). There are step by step instructions to replicating the event definition and meter in your tenant in the next section. But you can also just import these, the links are below.

While creating the source **Event Definition** is straightforward using `llm_usage.csv` here's a [json export](/assets/source-token-input-records.c4b4984787374137fbb56cd055b179105247ab7fba42d5dc7aff692a00f3891b.b4f54b07.json) of the event definition used in the video. And [here's an export of the meter used in the video](/assets/new-llm-tokens-meter.59adf426a2ab4b3c75d4b7d1321cb8c522d2a6a6c8892fa0a35266d4a398878d.b4f54b07.json), this is a json file and can be imported into your tenant using the **Import Meter** button on the main **Meters** page. To run the meter you'll need `llm_usage.csv - download` but edit in the Account Number for your tenant or the final step will error on every input record otherwise.

### Create a meter - step by step instructions

**1. Create the Event Definition**

1. Go to **Mediation** → **Meters** → **Event Definitions** → **Create New**
2. Name: `llm_tokens_usage`
3. Click **Use Sample Data** and upload [llm_usage.csv](/assets/llm_usage.21181400708c13a3b3bac62672b0a5a0ff4120a0456b371d6bef92a0bdbaf95b.b4f54b07.csv)
4. Scroll down and set:
  - **Specify event Id**: select `event_id`
  - **Specify Event Time**: select `event_time`


**2. Create the Meter and Add Source**

1. Select **Create Meter**, name it 'llm_tokens_meter', click **Custom**
2. The **Meter Stream** window opens
3. Click to add a **Source** (you'll see a '+' between Source and Processors)
4. In the **Upload File** dialog, click **Select** and choose 'llm_tokens_usage'
5. Click **OK**, review the fields (use **Rows per page** to see all), then click **Save**


**3. Set the Target**

1. Click the lower section and choose **Usage Records**
2. Map these fields to Zuora standard usage fields:
  - `event_time` → **Start Date Time**
  - `tenant_id` → **Account Number** (make sure you updated `llm_usage.csv` with your account number)
  - `input_tokens` → **Quantity** (temporary; we'll combine all three token fields in the next step)
  - `feature_name` → **UOM** (temporary placeholder; we'll correct this later)


**4. Add the Filter Processor**

1. Hover between **Upload File** and **Usage Records** and click the '+' to add a processor
2. Select **Add Processor** → **Filter**
3. Set up the filter rules:
  - Rule 1: `feature_name` **is not blank**
  - Click **+ Add Rule**
  - Rule 2: `model_name` **is not blank**
4. Click **Save** (records missing feature or model data will be filtered out)


**5. Add the Deduplicator Processor**

1. Click the '+' between **Filter** and **Usage Records**
2. Select **Add Processor** → **Deduplicator**
3. Choose **Specific Fields match** and select `event_id`
4. Keep other values at defaults (30-day rolling window)
5. Click **Save** (duplicate events within 30 days will be deduplicated)


**6. Add the Map Processor**

1. Click the '+' between **Deduplicator** and **Usage Records**
2. Select **Add Processor** → **Map**
3. Click **+ Add Field** (first field — set UOM):
  - Source: 'feature_name' → Target: 'uom'
  - Check **Transform Value**
  - **Target Field Value**: `'Token'` (include quotes)
  - Data type: **Text**
4. Click **+ Add Field** (second field — combine tokens):
  - Source: 'input_tokens' → Target: 'quantity'
  - Check **Transform Value**
  - **Target Field Value**: `event.input_tokens + event.output_tokens + event.cached_input_tokens`
  - Data type: **Number**
5. Click **Save**


**7. Test the Meter**

1. Click **Test** or **Run**
2. Upload [llm_usage.csv](/assets/llm_usage.21181400708c13a3b3bac62672b0a5a0ff4120a0456b371d6bef92a0bdbaf95b.b4f54b07.csv)
3. Verify `tenant_id` contains your Billing Account Number
4. Review results in the [monitoring meters video](/assets/zuora-mediation-monitoring-meters.b39a2d03d4a30fe7b6311f2548b478bf8385a228349db4fa5c6ecf696c8b395f.b4f54b07.mp4)


### Notes on debugging Meters

Review the [monitoring meters video](/assets/zuora-mediation-monitoring-meters.b39a2d03d4a30fe7b6311f2548b478bf8385a228349db4fa5c6ecf696c8b395f.b4f54b07.mp4). As you'll see each step or box in the meter can be examined to see what the inputs and outputs from that step are. While a later step may flag an error, you may need to step backwards, or 'up the chain', to see where the problem originates.

Not all errors are 'bad', we asked our meter to dedupe and filter, which it did, and was what we wanted. Establish a process to review running meters periodically and examine all errors to see if upstream corrective action is needed. Implement one or more of [Mediation's automated notifications](https://docs.zuora.com/en/zuora-platform/extensibility/mediation/events/notifications-in-mediation) to flag issues when they arise.

## Post meter run

When the meter runs it will generate 998 usage records in your Zuora tenant for the billing account you specified. A bill run for the 1st of the month after the usage records, by default this is August 1st 2026 will generate an invoice rating those usage records.

Previous: [Basics for all examples](/docs/get-started/tutorials/ai-monetization/basics-for-all-examples)

Next: [Commitment billing](/docs/get-started/tutorials/ai-monetization/commitment-billing)