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

# Pricing Models Reference

> Technical reference for pricing models used in subscription items

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" }`)  |

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

## Pricing Model Examples

### Unit Pricing

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

```json theme={null}
{
  "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).

```json theme={null}
{
  "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:

```json theme={null}
"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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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`.

<Note>
  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.
</Note>

## Discounts

Price-level discounts support both `percentage` and `fixed` types:

```json theme={null}
"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` |

<Note>
  Subscription-level discounts (set via PATCH) only support `percentage` type. Price-level discounts support both types.
</Note>

## Spending Thresholds

Both `minimum_spend` and `maximum_spend` use the same structure:

```json theme={null}
{
  "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 |