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

# Parameterized metrics

<Info>
  **This feature is in private preview.**

  Parameterized metrics are currently available to a limited set of customers. Reach out to your Orb contact to get access.
</Info>

Orb's [billable metrics](/events-and-metrics/construct-metrics) let you define a query over raw usage events to calculate meaningful billing values. In many cases, you want the *same* metric logic to apply across customers, but with a value that varies per subscription — a rate multiplier, a regional coefficient, or an allocation threshold.

**Parameterized billable metrics** solve this by letting you define named variables directly in your metric's SQL, and then set values for those variables on each subscription. This means you can write one metric and reuse it across your entire customer base, even when different customers have different contractual terms.

## Why parameterized metrics

Without parameters, modeling customer-specific rates requires creating a separate billable metric for each variation — a "Revenue at 1.5x" metric, a "Revenue at 2.0x" metric, and so on. This approach doesn't scale: every new contract negotiation means a new metric, and the list quickly becomes unmanageable.

Parameterized metrics let you define the logic once:

```sql theme={null}
SELECT SUM(amount * {{rate_multiplier}}) FROM events
WHERE event_name = 'transaction_processed'
```

The `{{rate_multiplier}}` placeholder is a **parameter**. When you create the metric, you give it a default value (e.g. `1.0`). When you create a subscription, you can override that value per price interval — one customer might get `1.5`, another `2.0`, and a third might use the default.

Orb resolves the parameter values at billing time and substitutes them into the query, so every downstream feature — usage dashboards, alerts, invoices — works exactly as it does with standard metrics.

## Defining parameters in SQL

Parameters use the `{{parameter_name}}` syntax inside a [custom SQL metric](/extensibility/advanced-metrics) definition. Parameter names must start with a letter or underscore and can contain alphanumeric characters and underscores.

```sql theme={null}
SELECT SUM(compute_seconds * {{cost_per_second}})
FROM events
WHERE event_name = 'job_completed'
```

You can use multiple parameters in a single metric:

```sql theme={null}
SELECT SUM(
  CASE
    WHEN region = {{target_region}} THEN quantity * {{premium_rate}}
    ELSE quantity
  END
)
FROM events
WHERE event_name = 'api_request'
```

Parameters can appear anywhere a literal value would — in arithmetic expressions, `CASE` conditions, `WHERE` clauses, and so on. They are not limited to numeric values; string parameters work as well (e.g. for filtering by a configurable region or tier name).

## Creating a parameterized metric

When you create a metric using custom SQL that contains `{{...}}` placeholders, Orb requires you to provide a **parameter definition** for each parameter. A parameter definition includes:

| Field           | Description                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `name`          | The parameter name, matching the `{{name}}` used in the SQL.                                   |
| `default_value` | The value to use when a subscription does not provide an override. Must be a number or string. |

The type of the parameter (numeric or string) is inferred from the `default_value` you provide. If the default is a number, Orb expects numeric overrides; if the default is a string, Orb expects string overrides.

### API

When creating a metric via the API, include the `parameter_definitions` field:

```json theme={null}
{
  "name": "Revenue with rate multiplier",
  "sql": "SELECT SUM(amount * {{rate_multiplier}}) FROM events WHERE event_name = 'transaction_processed'",
  "parameter_definitions": [
    {
      "name": "rate_multiplier",
      "default_value": 1.0
    }
  ]
}
```

### Validation rules

Orb validates parameter definitions against the SQL at creation time:

* Every `{{parameter}}` in the SQL must have a corresponding definition.
* Every definition must correspond to a `{{parameter}}` in the SQL — you cannot define unused parameters.
* A metric can have at most **10** parameter definitions.
* Each `default_value` must be a number or a string.

If validation fails, the metric creation request returns an error describing the mismatch.

## Overriding parameters on a subscription

Once you've attached a parameterized metric to a price on a plan, you can provide parameter overrides when [creating](/product-catalog/creating-subscriptions) or [editing](/product-catalog/editing-subscriptions) a subscription. Overrides are set **per price interval**, so different prices on the same subscription can use different values for the same parameter.

### API

When creating a subscription, include `price_metric_parameter_overrides`:

```json theme={null}
{
  "customer_id": "customer_abc",
  "plan_id": "plan_xyz",
  "price_metric_parameter_overrides": [
    {
      "price_id": "price_123",
      "metric_parameter_overrides": {
        "rate_multiplier": 2.5
      }
    }
  ]
}
```

You only need to specify the parameters you want to override. Any parameters not included in `metric_parameter_overrides` use the default value from the metric definition.

The same `price_metric_parameter_overrides` field is available when editing a subscription or scheduling a plan change.

### Validation rules

* Parameter names must match those defined on the metric.
* Override values must match the type of the parameter's default value (numeric overrides for numeric defaults, string overrides for string defaults).
* You cannot provide overrides for a price whose metric has no parameter definitions.

## How parameters are resolved

When Orb evaluates a parameterized metric — for invoicing, usage dashboards, or alerts — it resolves parameter values in the following order:

1. **Subscription override**: If the subscription's price interval specifies an override for a parameter, that value is used.
2. **Metric default**: If no override is provided, the default value from the metric's parameter definition is used.

The resolved values are substituted into the metric's SQL query as literal constants before execution. For example, with `rate_multiplier` resolved to `2.5`:

```sql theme={null}
-- What you define:
SELECT SUM(amount * {{rate_multiplier}}) FROM events WHERE event_name = 'transaction_processed'

-- What Orb executes:
SELECT SUM(amount * 2.5) FROM events WHERE event_name = 'transaction_processed'
```

Resolved parameter values are stored on each invoice line item for auditability, so you can always see exactly which values were used for a given billing period.

## Example use cases

**Customer-specific rate multipliers**

A payments platform charges per transaction, but enterprise customers negotiate custom rates. Define a single metric with a `{{rate_multiplier}}` parameter and override it per subscription:

```sql theme={null}
SELECT SUM(transaction_amount * {{rate_multiplier}}) FROM events
WHERE event_name = 'payment_captured'
```

Default: `1.0`. Customer A overrides to `0.8` (discounted). Customer B uses the default.

**Regional pricing coefficients**

A cloud provider charges differently for compute in different regions. Use a string parameter to filter by region and a numeric parameter for the regional rate:

```sql theme={null}
SELECT SUM(compute_hours * {{regional_rate}})
FROM events
WHERE event_name = 'compute_usage'
AND region = {{target_region}}
```

**Configurable thresholds**

A data platform charges for storage above a certain threshold. Make the threshold configurable per customer:

```sql theme={null}
SELECT GREATEST(MAX(storage_gb) - {{included_gb}}, 0)
FROM events
WHERE event_name = 'storage_measured'
```

Default: `100`. Customers on a higher tier override to `500`.

## Limits

* A metric can have at most **10** parameter definitions.
* Parameter names must start with a letter or underscore and can only contain alphanumeric characters and underscores.
* Default values must be a number (`int` or `float`) or a string.