> ## 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:

<CardGroup cols={2}>
  <Card title="Meter slug" icon="tag" horizontal>
    Unique identifier included in forward tokens to apply specific pricing
  </Card>

  <Card title="Fee model" icon="calculator" horizontal>
    Fixed credits per usage unit, or a percentage of provider cost
  </Card>

  <Card title="Usage units" icon="ruler" horizontal>
    What you're measuring — tokens, characters, seconds, or requests
  </Card>

  <Card title="Pricing tiers" icon="layer-group" horizontal>
    Volume-based rate schedules that reward higher usage
  </Card>
</CardGroup>

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

## Meter configuration

<Accordion title="Full create example with all parameters">
  <Tabs>
    <Tab title="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>

    <Tab title="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" }
          ]
        }'
      ```
    </Tab>
  </Tabs>
</Accordion>

## Usage units

Usage units define what metric drives pricing. Set via the <Tooltip tip="The tierType field on your meter configuration">tierType</Tooltip> 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 <Tooltip tip="The rateType field on your meter configuration">rateType</Tooltip> field determines how fees are calculated.

<Tabs>
  <Tab title="Fixed" icon="calculator">
    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>

  <Tab title="Percentage" icon="percent">
    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.
    </Warning>
  </Tab>
</Tabs>

## 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.
</Note>

<AccordionGroup>
  <Accordion title="Example: Three-tier token pricing" icon="chart-line" defaultOpen>
    | 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
  </Accordion>
</AccordionGroup>

<Tip>
  Tiers accumulate **per customer**. Each customer tracks total usage across all requests to determine the active tier.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Checkout" icon="credit-card" href="/monetize/checkout">
    Embed checkout to onboard paying customers
  </Card>

  <Card title="Gateway vs Post-Request" icon="route" href="/monetize/gateway-vs-post-request">
    Choose how usage gets reported to Lava
  </Card>
</CardGroup>