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

# Volume-Based Tiers

> Charge a single rate based on the total volume of usage

Volume-based pricing uses tiers to determine a single flat charge based on the total usage volume. Unlike [graduated pricing](/documentation/modelling-pricing/graduated-pricing), where each tier has its own rate, volume-based pricing charges a single flat amount based on which tier the total usage falls into.

> **Example** <br />
> A data platform charges:
>
> * 0–1,000 records: \$100 flat
> * 1,001–10,000 records: \$500 flat
> * 10,001+: \$1,000 flat
>
> A customer who processes 15,000 records falls into the 10,001+ tier and pays a flat **\$1,000**
>
> Compare this to graduated pricing, where each tier is charged separately and summed together

## Setting up

<Tabs>
  <Tab title="CLI">
    Use the `tiers` array with `tierBehavior: 'volume'` on a plan item price:

    ```ts autumn.config.ts theme={null}
    import { feature, item, plan } from 'atmn';

    export const records = feature({
      id: 'records',
      name: 'Records Processed',
      type: 'metered',
      consumable: true,
    });

    export const pro = plan({
      id: 'pro',
      name: 'Pro',
      price: { amount: 50, interval: 'month' },
      items: [
        item({
          featureId: records.id,
          reset: { interval: 'month' },
          price: {
            tiers: [
              { to: 1000, flatAmount: 100 },
              { to: 10000, flatAmount: 500 },
              { to: 'inf', flatAmount: 1000 },
            ],
            tierBehavior: 'volume',
            billingMethod: 'usage_based',
            interval: 'month',
          },
        }),
      ],
    });
    ```

    Push changes with `atmn push`.
  </Tab>

  <Tab title="Dashboard">
    1. Navigate to **Plans** and create or edit a plan
    2. Add a **consumable** feature
    3. Under **Price**, select **Tiered**
    4. Switch the tier behavior to **Volume**
    5. Add tiers with the upper limit (`to`) and flat amount (`flat_amount`) for each range
    6. Set the billing method to **Usage-based** and the billing interval
    7. Save the plan
  </Tab>
</Tabs>

## How volume-based pricing works

At the end of the billing period, Autumn:

1. Looks at the total usage for the feature
2. Finds the tier the total falls into
3. Charges the flat amount for that tier

| Total usage | Matching tier | Charge      |
| ----------- | ------------- | ----------- |
| 500         | 0–1,000       | **\$100**   |
| 5,000       | 1,001–10,000  | **\$500**   |
| 15,000      | 10,001+       | **\$1,000** |

## Tier configuration

Each tier has the following fields:

| Field         | Type              | Description                                                                            |
| ------------- | ----------------- | -------------------------------------------------------------------------------------- |
| `to`          | number or `"inf"` | The upper boundary of this tier                                                        |
| `flat_amount` | number            | Flat fee charged when total usage falls in this tier                                   |
| `amount`      | number            | Optional per-unit price applied to the total usage when this tier is the matching tier |

<Note>
  Tiers must be in ascending order by `to`. The final tier should use `"inf"`.
</Note>

## Combining flat and per-unit amounts

Each tier can include both `flat_amount` and `amount` — a fixed fee plus a per-unit charge when that tier is the matching tier. This is useful for combining a base fee with per-unit volume pricing.

```ts theme={null}
price: {
  tiers: [
    { to: 1000, amount: 0.10, flat_amount: 0 },
    { to: 10000, amount: 0.08, flat_amount: 50 },
    { to: 'inf', amount: 0.05, flat_amount: 100 },
  ],
  tierBehavior: 'volume',
  billingMethod: 'usage_based',
  interval: 'month',
}
```

A customer with 5,000 records would pay: (5,000 × $0.08) + $50 = **\$450**

## Graduated vs volume-based

|                  | Graduated                                  | Volume-based                             |
| ---------------- | ------------------------------------------ | ---------------------------------------- |
| **Rate applied** | Each tier at its own rate                  | Single flat amount for the matching tier |
| **Total charge** | Sum of each tier's charge                  | Flat amount of the matching tier         |
| **Best for**     | Rewarding growth with lower marginal rates | Simpler pricing with volume discounts    |

See [Graduated Pricing](/documentation/modelling-pricing/graduated-pricing) for the alternative model.