Coupons: applying a discount to a specific billable metric filter value

Last updated: August 17, 2026

When using billable metrics with filters (e.g., a model filter with multiple values), coupons can be scoped to a billable metric but not to a specific filter value within that metric. If you need to apply a coupon to only one filter value, the coupon will apply to the entire metric, covering all filter values.

To target a coupon at a single filter value, that value must be represented as its own dedicated billable metric.

Applies to

  • Surface: Dashboard, API

  • Object or endpoint: Billable metrics, filters, coupons

  • Condition: Billable metric uses filters with multiple values, and a coupon must be scoped to only one of those values

Cause

Lago's coupon scoping operates at the billable metric level, not at the filter value level. When a billable metric has a filter with multiple values (e.g., model: value-a and model: value-b), there is no mechanism to restrict a coupon to only one of those values. The coupon applies to the metric as a whole.

How to confirm the cause

When configuring a coupon in the Dashboard or via the API, check the available scoping options. You will find that you can select a billable metric, but there is no additional option to restrict the coupon to a specific filter value within that metric.

  • Matching signal: The coupon configuration UI or API only allows selecting a billable metric, with no filter value selector available.

  • Non-matching signal: If your billable metric has no filters, or if you want the coupon to apply to all filter values equally, this limitation does not affect you.

How to resolve the issue

Split the filter value you want to target into its own dedicated billable metric.

  1. Create a new billable metric specifically for the filter value you want to discount (e.g., a metric named transcription_hours_model_b representing only that model).

  2. Update your event ingestion to send usage events to the appropriate billable metric based on the model used.

  3. Create the coupon and scope it to the new dedicated billable metric.

  4. Verify that the coupon applies only to usage tracked under the new metric and not to the other model(s).

Expected result: The coupon is applied exclusively to the billable metric representing the targeted filter value, leaving usage from other filter values unaffected.