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

Common Fields

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

Field	Type	Required	Description
`type`	string	Yes	One of the 10 pricing types above
`billing_interval`	string	Yes	`monthly`, `quarterly`, `semi_annual`, or `yearly`
`fee_type`	string	Yes	`fixed` or `metered`
`billing_direction`	string	Yes	`advance` (start of period) or `arrears` (end of period)
`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
`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": ["met_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": ["met_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": ["met_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": ["met_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": ["met_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": ["met_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": ["met_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": ["met_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. met_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": ["met_compute_hours", "met_api_calls"],
  "expression_pricing_model": {
    "metric_bindings": [
      { "alias": "compute_hours", "metric_id": "met_compute_hours" },
      { "alias": "api_calls", "metric_id": "met_api_calls" }
    ],
    "charges": [
      {
        "billing_direction": "charge",
        "description": "Compute usage charge",
        "quantity_expression": "met_compute_hours",
        "unit_price_expression": "0.01 * (1 - min(met_compute_hours / 100000, 0.5))"
      },
      {
        "billing_direction": "charge",
        "description": "API overage",
        "quantity_expression": "met_api_calls > 1000 ? met_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.

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`, `rolling`, or `perpetual`
`duration_value`	integer	Conditional	Required when `duration_type` is `fixed`
`duration_unit`	string	Conditional	Required when `duration_type` is `fixed`. Values: `days`, `weeks`, `months`, `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`

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

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

​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

​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

Discounts

Spending Thresholds

Tier Structure

Standard Tiers (unit-based pricing models)

Percentage Tiers