Skip to main content
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.
Orb’s billable 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: 
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 definition. Parameter names must start with a letter or underscore and can contain alphanumeric characters and underscores. 
SELECT SUM(compute_seconds * {{cost_per_second}})
FROM events
WHERE event_name = 'job_completed'
You can use multiple parameters in a single metric: 
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:
FieldDescription
nameThe parameter name, matching the {{name}} used in the SQL.
default_valueThe 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: 
{
  "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 or editing 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: 
{
  "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: 
-- 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: 
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: 
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: 
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.