Pricing Models Reference

When creating or viewing subscription items, each item has a price object containing a type field that determines which pricing model is used. Exactly one pricing model field will be populated, matching the type.

Supported Pricing Types

Type	Model Field	Description
`unit`	`unit_pricing_model`	Simple per-unit rate
`fixed`	`fixed_pricing_model`	Flat amount for a fixed quantity
`tiered`	`tiered_pricing_model`	Total usage determines the tier; all units priced at that tier’s rate
`graduated_tiered`	`graduated_tiered_pricing_model`	Each tier priced independently (units 0-100 at rate A, 101-500 at rate B)
`tiered_percentage`	`tiered_percentage_pricing_model`	Percentage-based tiers (first matching tier applies)
`graduated_percentage`	`graduated_percentage_pricing_model`	Graduated percentage tiers (each tier priced independently)
`volume_percentage`	`volume_percentage_pricing_model`	Percentage of transaction volume with base rate
`prepaid_tiered`	`prepaid_tiered_pricing_model`	Pre-purchased units with tiered overage rates
`prepaid_fixed_tiered`	`prepaid_fixed_tiered_pricing_model`	Pre-purchased units with tiered overages and configurable overage interval
`expression`	`expression_pricing_model`	Custom expression-based pricing
`matrix`	`matrix_pricing_model`	Routes each event to a priced cell by its property values

fee_type is set independently of type: a unit price can be fixed or metered. Set it to match how the charge behaves, and supply metric_ids whenever it is metered.

Common Fields

Every price includes these fields alongside the model-specific field:

Field	Type	Required	Description
`type`	string	Yes	One of the 11 pricing types above
`fee_type`	string	Yes	`fixed` or `metered`
`billing_direction`	string	Yes	`advance` (start of period) or `arrears` (end of period)
`billing_interval_unit`	string	No	Unit of the billing cadence: `day`, `week`, `month` or `year`. Currently only `month` is accepted
`billing_interval_count`	integer	No	How many `billing_interval_unit`s make up a period
`billing_interval`	string	No	Legacy named interval: `monthly`, `quarterly`, `semi_annual` or `yearly`. Prefer the unit and count pair above
`billing_frequency`	string	No	`recurring` or `one-off`. Required for fixed fee type
`metric_ids`	string[]	Conditional	Required for metered fee type. Which metrics drive usage
`recurring_instalment_interval_unit`	string	No	Optional sub-cadence splitting an advance charge into instalments within a period
`recurring_instalment_interval_count`	integer	No	How many of those units per instalment. Must divide the billing cadence evenly
`display_order`	integer	No	Sort order for display
`charge_on_contract_start`	boolean	No	For one-off prices: charge on contract start instead of first billing date
`trial_period_days`	integer	No	Days before billing starts (minimum 1)
`discount`	object	No	Price-level discount
`minimum_spend`	object	No	Floor spend per period (`{ "amount": "500.00", "period": "monthly" }`)
`maximum_spend`	object	No	Ceiling spend per period (`{ "amount": "5000.00", "period": "monthly" }`)

When creating prices, currency is inherited from the subscription and should not be specified. In responses, currency is always included.

Pricing Model Examples

Unit Pricing

Simple per-unit rate. Best for metered products where each unit costs the same.

{
  "type": "unit",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_api_calls"],
  "unit_pricing_model": {
    "price_per_unit": "0.05"
  }
}

Fixed Pricing

Flat amount for a fixed quantity of units. total is computed server-side (not required in requests).

{
  "type": "fixed",
  "billing_interval": "monthly",
  "fee_type": "fixed",
  "billing_direction": "arrears",
  "billing_frequency": "recurring",
  "fixed_pricing_model": {
    "price_per_unit": "500.00",
    "units": 1
  }
}

In responses, the total field is included:

"fixed_pricing_model": {
  "price_per_unit": "500.00",
  "units": 1,
  "total": "500.00"
}

Tiered Pricing

Total usage determines which tier applies. All units are priced at that single tier’s rate.

{
  "type": "tiered",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_api_calls"],
  "tiered_pricing_model": {
    "tiers": [
      { "min_units": 0, "max_units": 1000, "price_per_unit": "0.20", "fixed_fee": null },
      { "min_units": 1001, "max_units": 10000, "price_per_unit": "0.15", "fixed_fee": null },
      { "min_units": 10001, "max_units": null, "price_per_unit": "0.10", "fixed_fee": null }
    ]
  }
}

Graduated Tiered Pricing

Each tier is priced independently. Units 0-1000 at

0.20, units 1001-10000 at

0.15, etc.

{
  "type": "graduated_tiered",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_api_calls"],
  "graduated_tiered_pricing_model": {
    "tiers": [
      { "min_units": 0, "max_units": 1000, "price_per_unit": "0.20", "fixed_fee": null },
      { "min_units": 1001, "max_units": 10000, "price_per_unit": "0.15", "fixed_fee": null },
      { "min_units": 10001, "max_units": null, "price_per_unit": "0.10", "fixed_fee": null }
    ]
  }
}

Tiered Percentage Pricing

Percentage-based tiers. Total usage determines which tier’s percentage applies to all units.

{
  "type": "tiered_percentage",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_revenue"],
  "tiered_percentage_pricing_model": {
    "tiers": [
      { "min_units": 0, "max_units": 100000, "percentage": "2.9", "fixed_fee": "0.30" },
      { "min_units": 100001, "max_units": null, "percentage": "1.5", "fixed_fee": null }
    ]
  }
}

Graduated Percentage Pricing

Each tier’s percentage applies independently to the units within that tier.

{
  "type": "graduated_percentage",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_revenue"],
  "graduated_percentage_pricing_model": {
    "tiers": [
      { "min_units": 0, "max_units": 100000, "percentage": "2.9", "fixed_fee": "0.30" },
      { "min_units": 100001, "max_units": null, "percentage": "1.5", "fixed_fee": null }
    ]
  }
}

Volume Percentage Pricing

Charges a percentage of transaction volume plus an optional fixed fee per transaction.

{
  "type": "volume_percentage",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_payments"],
  "volume_percentage_pricing_model": {
    "price_per_unit": "0.00",
    "percentage": "2.9",
    "fixed_fee": "0.30"
  }
}

Prepaid Tiered Pricing

Customer pre-purchases a block of units. Overages are charged at tiered rates.

{
  "type": "prepaid_tiered",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_api_calls"],
  "prepaid_tiered_pricing_model": {
    "prepaid_units": 50000,
    "tiers": [
      { "min_units": 0, "max_units": 10000, "price_per_unit": "0.02", "fixed_fee": null },
      { "min_units": 10001, "max_units": null, "price_per_unit": "0.01", "fixed_fee": null }
    ]
  }
}

Prepaid Fixed Tiered Pricing

Like prepaid tiered, but with a configurable overage charge interval.

{
  "type": "prepaid_fixed_tiered",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_api_calls"],
  "prepaid_fixed_tiered_pricing_model": {
    "prepaid_units": 50000,
    "overages_charge_interval": "monthly",
    "tiers": [
      { "min_units": 0, "max_units": 10000, "price_per_unit": "0.02", "fixed_fee": null },
      { "min_units": 10001, "max_units": null, "price_per_unit": "0.01", "fixed_fee": null }
    ]
  }
}

Expression Pricing

Custom expression-based pricing. Each charge is a pair of formulas — one for the quantity, one for the unit price — evaluated with decimal precision. Referencing metrics. An expression references a bound metric directly by its metric ID (e.g. mtr_compute_hours) — metric IDs are valid expression identifiers, so no separate name is needed to use one in a formula. metric_bindings optionally gives a metric a short alias purely for display in the pricing editor UI; the alias itself is never a legal expression variable and never appears in a stored or evaluated expression. Every bound metric must also appear in metric_ids.

{
  "type": "expression",
  "billing_interval": "monthly",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "metric_ids": ["mtr_compute_hours", "mtr_api_calls"],
  "expression_pricing_model": {
    "metric_bindings": [
      { "alias": "compute_hours", "metric_id": "mtr_compute_hours" },
      { "alias": "api_calls", "metric_id": "mtr_api_calls" }
    ],
    "charges": [
      {
        "billing_direction": "arrears",
        "description": "Compute usage charge",
        "quantity_expression": "mtr_compute_hours",
        "unit_price_expression": "0.01 * (1 - min(mtr_compute_hours / 100000, 0.5))"
      },
      {
        "billing_direction": "arrears",
        "description": "API overage",
        "quantity_expression": "mtr_api_calls > 1000 ? mtr_api_calls - 1000 : 0",
        "unit_price_expression": "0.002"
      }
    ]
  }
}

Available variables

Variable	Meaning
`<metric_id>`	The bound metric’s aggregated value over the current billing period
`<metric_id>_count`	The number of usage events for that bound metric over the current billing period
`usage`	Sum of all of the price’s metrics over the billing period. Available only when the price has no `metric_bindings`
`event_count`	Number of usage events over the billing period. Available only when the price has no `metric_bindings`

usage and event_count are back-compat variables for a price with no bindings. As soon as you bind any metric via metric_bindings, they leave scope — address each metric’s value through its <metric_id> and its event count through <metric_id>_count. metric_bindings[].alias is a display-only name for the pricing editor UI — it must be a valid identifier, must not collide with usage/event_count, and must not end in _count (so the editor can unambiguously tell an alias like requests_count apart from the auto-derived _count display name it generates for a different alias, e.g. requests). None of this alias hygiene affects evaluation: an alias is never itself a legal expression variable, at save time or at charge time. Operators & functions: arithmetic (+ - * /), comparisons (> >= < <= ==), ternary conditionals (condition ? a : b), and min / max / abs.

Every variable resolves over the current billing period. Longer-horizon aggregates (contract-to-date, all-time) and contract lifecycle values (term, days remaining, …) are intentionally excluded — those are re-pricing conditions handled by escalation/re-pricing automations, not inputs to a charge formula.

Matrix Pricing

Routes each usage event to a priced cell based on its property values, so a rate can vary along more than one dimension at once. Each cell carries its own pricing model, so one branch can be a flat per-unit rate while another is tiered. A matrix has two parts:

dimensions — the event property keys the matrix routes on, with display labels. values lists the values you author in the UI; it does not restrict what the matrix can match at charge time.
root — a routing tree. Each node either holds a leaf (the priced cell) or splits (ordered routing choices). A split names a dimension_key and lists exact-value branches; wildcard catches a value that is present but has no exact branch, and fallback catches an event that no split claims at all.

{
  "type": "matrix",
  "fee_type": "metered",
  "billing_direction": "arrears",
  "billing_interval": "monthly",
  "metric_ids": ["mtr_api_calls"],
  "matrix_pricing_model": {
    "line_item_template": "{product} / {region}",
    "dimensions": [
      { "key": "region", "label": "Region", "values": ["eu", "us"] }
    ],
    "root": {
      "splits": [
        {
          "dimension_key": "region",
          "branches": [
            {
              "value": "eu",
              "child": {
                "leaf": {
                  "type": "unit",
                  "label": "API requests (EU)",
                  "unit_pricing_model": { "price_per_unit": "0.25" }
                }
              }
            }
          ],
          "wildcard": {
            "leaf": {
              "type": "tiered",
              "label": "API requests (other regions)",
              "tiered_pricing_model": {
                "tiers": [
                  { "min_units": 0, "max_units": 100, "price_per_unit": "0" },
                  { "min_units": 100, "price_per_unit": "0.20" }
                ]
              }
            }
          }
        }
      ],
      "fallback": {
        "leaf": {
          "type": "unit",
          "label": "API requests (region not set)",
          "unit_pricing_model": { "price_per_unit": "0.30" }
        }
      }
    }
  }
}

An event carrying region: "eu" is charged at 0.25 per unit. An event carrying any other region value falls to the wildcard and is charged on the tiered schedule. An event with no region property at all is charged by the fallback cell at 0.30. Cell pricing models. A cell’s type may be unit, fixed, tiered, graduated_tiered, tiered_percentage, graduated_percentage or volume_percentage, with the matching *_pricing_model object. expression, matrix and the prepaid types cannot be used inside a cell. line_item_template sets the default invoice line description for cells, interpolating dimension keys in single braces (for example {product} / {region}). A cell’s own label overrides it, including an explicitly empty label.

Omit cell_key when creating a matrix. It is the stable identity of an existing cell, returned in responses, and is used to preserve a cell’s identity when you update the matrix later.

Discounts

Price-level discounts support both percentage and fixed types:

"discount": {
  "type": "percentage",
  "amount": "20",
  "duration_type": "fixed",
  "duration_value": 3,
  "duration_unit": "months"
}

Field	Type	Required	Description
`type`	string	Yes	`percentage` or `fixed`
`amount`	string	Yes	Discount amount (percentage value or fixed amount)
`duration_type`	string	Yes	`fixed` (runs for a set duration) or `monthly_rolling` (renews each month until removed)
`duration_value`	integer	Conditional	Required when `duration_type` is `fixed`
`duration_unit`	string	Conditional	Required when `duration_type` is `fixed`. Values: `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `quarters`, `years`

Subscription-level discounts (set via PATCH) only support percentage type. Price-level discounts support both types.

Spending Thresholds

Both minimum_spend and maximum_spend use the same structure:

{
  "amount": "500.00",
  "period": "monthly"
}

Field	Type	Required	Description
`amount`	string	Yes	Threshold amount (must be greater than 0)
`period`	string	Yes	Billing period: `monthly`, `quarterly`, `semi_annual`, or `yearly`
`billing_direction`	string	No	On a `minimum_spend`, `advance` bills the minimum up front and draws it down as spend accrues, instead of truing it up in `arrears`

Tier Structure

Standard Tiers (unit-based pricing models)

Used by tiered, graduated_tiered, prepaid_tiered, and prepaid_fixed_tiered models:

Field	Type	Required	Description
`min_units`	integer	Yes	Lower bound of the tier (inclusive)
`max_units`	integer	No	Upper bound (null = unlimited)
`price_per_unit`	string	No	Price charged per unit in this tier
`fixed_fee`	string	No	Fixed fee charged when this tier is active
`unit_price`	string	No	Committed per-unit rate, for the commitment tier of a prepaid-with-overages model

Percentage Tiers

Used by tiered_percentage and graduated_percentage models:

Field	Type	Required	Description
`min_units`	integer	Yes	Lower bound of the tier (inclusive)
`max_units`	integer	No	Upper bound (null = unlimited)
`percentage`	string	No	Percentage rate applied in this tier
`fixed_fee`	string	No	Fixed fee charged when this tier is active

API Reference

Examples

SDKs

API Reference

Webhooks

Pricing Models Reference

Supported Pricing Types

Common Fields

Pricing Model Examples

Unit Pricing

Fixed Pricing

Tiered Pricing

Graduated Tiered Pricing

Tiered Percentage Pricing

Graduated Percentage Pricing

Volume Percentage Pricing

Prepaid Tiered Pricing

Prepaid Fixed Tiered Pricing

Expression Pricing

Matrix Pricing

Discounts

Spending Thresholds

Tier Structure

Standard Tiers (unit-based pricing models)

Percentage Tiers

​Supported Pricing Types

​Common Fields

​Pricing Model Examples

​Unit Pricing

​Fixed Pricing

​Tiered Pricing

​Graduated Tiered Pricing

​Tiered Percentage Pricing

​Graduated Percentage Pricing

​Volume Percentage Pricing

​Prepaid Tiered Pricing

​Prepaid Fixed Tiered Pricing

​Expression Pricing

​Matrix Pricing

​Discounts

​Spending Thresholds

​Tier Structure

​Standard Tiers (unit-based pricing models)

​Percentage Tiers

Supported Pricing Types

Common Fields

Pricing Model Examples

Unit Pricing

Fixed Pricing

Tiered Pricing

Graduated Tiered Pricing

Tiered Percentage Pricing

Graduated Percentage Pricing

Volume Percentage Pricing

Prepaid Tiered Pricing

Prepaid Fixed Tiered Pricing

Expression Pricing

Matrix Pricing

Discounts

Spending Thresholds

Tier Structure

Standard Tiers (unit-based pricing models)

Percentage Tiers