> ## Documentation Index
> Fetch the complete documentation index at: https://lava.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Meters

> Configure pricing rules for your AI services using meters: fixed credits per usage unit, percentage markups on provider cost, and tiered rates

A **meter** defines how you price and bill usage. Each meter has:

> [card] Meter slug
>
> Unique identifier included in forward tokens to apply specific pricing

> [card] Fee model
>
> Fixed credits per usage unit, or a percentage of provider cost

> [card] Usage units
>
> What you're measuring — tokens, characters, seconds, or requests

> [card] Pricing tiers
>
> Volume-based rate schedules that reward higher usage

Meters define pricing. [Plans](https://lava.so/docs/monetize/plans.md) link to meters and provide the credit balance that usage draws from. See [How Lava Monetize Works](https://lava.so/docs/monetize/how-lava-monetize-works.md) for the full picture of how meters, plans, and customers fit together.

## Meter configuration

> [accordion] Full create example with all parameters
>
> > [tab] Node.js SDK
> >
> > ```typescript theme={null}
> > const meter = await lava.meters.create({
> >   // Required
> >   name: 'Chat Completion Tokens',
> >
> >   // Optional — auto-generated if omitted
> >   meter_slug: 'chat-tokens',
> >
> >   // Required — 'fixed' (credits per usage unit) or 'percentage' (markup on provider cost)
> >   rate_type: 'fixed',
> >
> >   // Required — 'tokens_1m' | 'characters_1m' | 'minutes' | 'requests'
> >   tier_type: 'tokens_1m',
> >
> >   // Required — at least one tier, first tier must start at '0'
> >   tiers: [
> >     { start: '0', rate: '5.00' },        // 5 credits per 1M tokens
> >     { start: '1000000', rate: '3.00' },   // 3 credits per 1M after 1M
> >     { start: '10000000', rate: '1.00' },  // 1 credit per 1M after 10M
> >   ],
> > });
> > ```
>
> > [tab] cURL
> >
> > ```bash theme={null}
> > curl -X POST 'https://api.lava.so/v1/meters' \
> >   -H 'Authorization: Bearer sk_your_secret_key' \
> >   -H 'Content-Type: application/json' \
> >   -d '{
> >     "name": "Chat Completion Tokens",
> >     "meter_slug": "chat-tokens",
> >     "rate_type": "fixed",
> >     "tier_type": "tokens_1m",
> >     "tiers": [
> >       { "start": "0", "rate": "5.00" },
> >       { "start": "1000000", "rate": "3.00" },
> >       { "start": "10000000", "rate": "1.00" }
> >     ]
> >   }'
> > ```

## Usage units

Usage units define what metric drives pricing. Set via the tierType (The tierType field on your meter configuration) field:

| Unit type | Label | Rate basis | Example use case |
| - | - | - | - |
| `tokens_1m` | Tokens | credits per 1M tokens | LLM APIs |
| `characters_1m` | Characters | credits per 1M characters | Text-to-speech |
| `minutes` | Seconds | credits per minute | Audio processing, voice calls |
| `requests` | Requests | credits per request | Image generation, API calls |

## Fee models

The rateType (The rateType field on your meter configuration) field determines how fees are calculated.

> [tab] Fixed
>
> Charge a fixed number of **credits** per usage unit (tokens, characters, time, or requests), regardless of the provider's dollar cost:
>
> ```
> credits_charged = rate × units
> ```
>
> **Example:** `2` credits per 1M tokens with `input+output` basis
>
> * 500 input tokens + 200 output tokens = 700 tokens
> * Credits: `2 × 700 / 1,000,000 = 0.0014` credits

> [tab] Percentage
>
> Charge a percentage of the base provider cost. The rate represents what percentage of the provider cost your customer pays — **not** the markup on top.
>
> ```
> customer cost = baseCost × rate / 100
> ```
>
> **Example:** 20% markup → set rate to `120`
>
> * Provider charges \$0.01 for a request
>
> * Customer pays: \$0.01 × 120 / 100 = **\$0.012**
>
> > [!WARNING]
> >
> > The rate is the **total percentage of provider cost** the customer pays. For a 20% markup, set the rate to `120` (not `20`). Setting the rate to `20` would charge the customer only 20% of the provider cost.

## Pricing tiers

Tiers let you offer volume-based pricing. Each tier defines a usage threshold and rate. As cumulative usage increases, later tiers apply.

> [!NOTE]
>
> At least one tier is required. The first tier must start at `0`, and tier starts must be in ascending order.

> [accordion] Example: Three-tier token pricing
>
> | Tier | Start | Rate (credits per 1M tokens) |
> | - | - | - |
> | 1 | 0 | 5 |
> | 2 | 1,000,000 | 3 |
> | 3 | 10,000,000 | 1 |
>
> For a customer that uses 5M tokens total:
>
> * First 1M at 5 credits/1M = **5 credits**
> * Next 4M at 3 credits/1M = **12 credits**
> * **Total: 17 credits** deducted from their balance

> [!TIP]
>
> Tiers accumulate **per customer**. Each customer tracks total usage across all requests to determine the active tier.

## Next steps

> [card] [Checkout](https://lava.so/docs/monetize/checkout.md)
>
> Embed checkout to onboard paying customers

> [card] [Gateway vs Post-Request](https://lava.so/docs/monetize/gateway-vs-post-request.md)
>
> Choose how usage gets reported to Lava


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.