# Pricing Models

Pricing models define how customers are charged. Set the `pricing_model` field on a Price entity to control the calculation method.

## Overview

| Model | Type | Description |
|---|---|---|
| `per_unit` | Unit-based or flat-fee | Fixed amount per unit of quantity |
| `tiered_volume` | Unit-based | Single tier applies to all units based on total quantity |
| `tiered_graduated` | Unit-based | Each tier's rate applies only to units within that tier's range |
| `tiered_flatfee` | Flat-fee | Flat fee determined by which tier the quantity falls into |

All models support **variable pricing** -- when `variable_price` is enabled, the total is calculated dynamically from user input (e.g., estimated annual energy consumption).

> **Tip: For energy tariffs, `tiered_graduated` is the most common model -- it mirrors how grid fees and energy prices are typically structured with consumption-based tiers.**

---

## Standard (`per_unit`)

Charges a fixed amount per unit. When `variable_price=true`, the total is calculated from user input (e.g., consumption).

```json
{
  "pricing_model": "per_unit",
  "variable_price": true,
  "unit_amount_decimal": "0.055",
  "unit_amount": 6,
  "unit_amount_currency": "EUR"
}
```

**Calculation:**

```
Consumption = 2,000 kWh
Total = 2,000 kWh x 0.055 EUR/kWh = 110.00 EUR
```

---

## Tiered Volume (`tiered_volume`)

The customer's total quantity determines a single tier, and that tier's unit price applies to **all** units.

```json
{
  "pricing_model": "tiered_volume",
  "variable_price": true,
  "unit_amount_currency": "EUR",
  "tiers": [
    { "unit_amount_decimal": "0.055", "up_to": 1000 },
    { "unit_amount_decimal": "0.054", "up_to": 2000 },
    { "unit_amount_decimal": "0.053", "up_to": 3000 },
    { "unit_amount_decimal": "0.050" }
  ]
}
```

**Calculation:**

```
Consumption = 2,000 kWh → falls in tier 2 (up to 2,000)
Total = 2,000 kWh x 0.054 EUR/kWh = 108.00 EUR
```

The last tier (no `up_to`) acts as a catch-all for quantities exceeding all defined ranges.

---

## Tiered Graduated (`tiered_graduated`)

Each tier's unit price applies only to units **within that tier's range**. Lower tiers keep their price as consumption crosses into higher tiers. This is sometimes called "cumulative" or "staircase" pricing.

```json
{
  "pricing_model": "tiered_graduated",
  "variable_price": true,
  "unit_amount_currency": "EUR",
  "tiers": [
    { "unit_amount_decimal": "0.055", "up_to": 1000 },
    { "unit_amount_decimal": "0.054", "up_to": 2000 },
    { "unit_amount_decimal": "0.053", "up_to": 3000 },
    { "unit_amount_decimal": "0.050" }
  ]
}
```

**Calculation:**

```
Consumption = 2,000 kWh
  Tier 1: 1,000 kWh x 0.055 EUR/kWh =  55.00 EUR
  Tier 2: 1,000 kWh x 0.054 EUR/kWh =  54.00 EUR
  Total                                = 109.00 EUR
```

---

## Tiered Flat Fee (`tiered_flatfee`)

Charges a flat fee based on which tier the quantity falls into. The customer pays the tier's flat fee regardless of exact quantity.

```json
{
  "pricing_model": "tiered_flatfee",
  "variable_price": true,
  "unit_amount_currency": "EUR",
  "tiers": [
    { "flat_fee_amount_decimal": "50.00", "up_to": 5 },
    { "flat_fee_amount_decimal": "100.00", "up_to": 7 },
    { "flat_fee_amount_decimal": "150.00", "up_to": 3000 },
    { "flat_fee_amount_decimal": "200.00" }
  ]
}
```

**Calculation:**

```
Max peak power = 7 kW → falls in tier 2 (up to 7)
Total = 100.00 EUR (flat fee)
```

---

## Tier Selection and Input Precedence

Tier ranges are defined by the `up_to` field. The customer's consumption determines which tier applies. For graduated models, all tiers up to the matched tier contribute.

Consumption comes from two possible sources:

| Priority | Source | Where it's set |
|---|---|---|
| 1 | Mapping input | Number input block in a [Journey](/docs/journeys/journey-builder), or mapping input on an [Order](/docs/pricing/orders) |
| 2 | Quantity input | Product selection block in a [Journey](/docs/journeys/journey-builder), or quantity input on an [Order](/docs/pricing/orders) |

If both inputs are provided, the **mapping input takes precedence**. If neither is provided, consumption defaults to `1`.

> **Tip: Use the [Pricing Library](https://www.npmjs.com/package/@epilot/pricing) to perform price calculations client-side in Journeys or server-side in automation flows. It handles all pricing models, tax breakdowns, and billing period normalization.**

## Billing Periods

All pricing models support the following billing periods:

| Period | Value |
|---|---|
| One-time | `one_time` |
| Weekly | `weekly` |
| Monthly | `monthly` |
| Quarterly | `every_quarter` |
| Semi-annual | `every_6_months` |
| Annual | `yearly` |

The [Pricing Library](https://www.npmjs.com/package/@epilot/pricing) includes normalization utilities for converting amounts between billing periods (e.g., displaying a yearly rate as a monthly equivalent).