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).

{
  "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.

{
  "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.

{
  "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.

{
  "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, or mapping input on an Order
2	Quantity input	Product selection block in a Journey, or quantity input on an Order

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

tip

Use the Pricing Library 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 includes normalization utilities for converting amounts between billing periods (e.g., displaying a yearly rate as a monthly equivalent).