SaaSBillingMetered · Traits

Fields it adds

Field	Type	Required	Description
`meter_name`	`string`	yes	Friendly metered feature name shown in UI (ex: Analytics Seats).
`included_quantity`	`integer`	yes	Quantity included in base plan before overages.
`consumed_quantity`	`integer`	yes	Actual quantity consumed in the active period.
`unit_label`	`string`	yes	Label for display, defaults to the unit parameter.
`period_start`	`date`	yes	Date the usage accumulation window began.
`period_end`	`date`	yes	Date the usage accumulation window ends.
`rollover_strategy`	`string`	no	Strategy for unused units (inherits rolloverStrategy parameter).
`overage_rate_minor`	`integer`	no	Cost per additional unit expressed in minor currency units.
`projected_overage_minor`	`integer`	no	Forecasted overage spend derived from consumption trends.
`samples`	`UsageSample[]`	no	Rolling usage measurements for charts or anomaly detection.

What it shows in each context

This trait places no component of its own.

Parameters

unit string, required: Canonical usage unit label (ex: seats, credits, api_calls).
rolloverStrategy string: Determines how unused units are treated at period end.
sampleWindowDays integer: Rolling window size used to calculate usage deltas.

Objects that use it

The trait file

domains/saas-billing/traits/metered.trait.yaml

trait:
  name: SaaSBillingMetered
  version: 1.0.0
  description: Provides usage metering fields for consumption based billing with normalized units and rollover policy.
  category: domain
  tags:
    - billing
    - usage
    - domain

parameters:
  - name: unit
    type: string
    required: true
    description: "Canonical usage unit label (ex: seats, credits, api_calls)."
    default: seats
  - name: rolloverStrategy
    type: string
    required: false
    description: Determines how unused units are treated at period end.
    default: none
    validation:
      enum:
        - none
        - carry_forward
        - expire
  - name: sampleWindowDays
    type: integer
    required: false
    description: Rolling window size used to calculate usage deltas.
    default: 30

schema:
  meter_name:
    type: string
    required: true
    description: "Friendly metered feature name shown in UI (ex: Analytics Seats)."
  included_quantity:
    type: integer
    required: true
    description: Quantity included in base plan before overages.
  consumed_quantity:
    type: integer
    required: true
    description: Actual quantity consumed in the active period.
  unit_label:
    type: string
    required: true
    description: Label for display, defaults to the unit parameter.
    defaultFromParameter: unit
  period_start:
    type: date
    required: true
    description: Date the usage accumulation window began.
  period_end:
    type: date
    required: true
    description: Date the usage accumulation window ends.
  rollover_strategy:
    type: string
    required: false
    description: Strategy for unused units (inherits rolloverStrategy parameter).
    defaultFromParameter: rolloverStrategy
  overage_rate_minor:
    type: integer
    required: false
    description: Cost per additional unit expressed in minor currency units.
  projected_overage_minor:
    type: integer
    required: false
    description: Forecasted overage spend derived from consumption trends.
  samples:
    type: UsageSample[]
    required: false
    description: Rolling usage measurements for charts or anomaly detection.
    default: []

semantics:
  meter_name:
    semantic_type: billing.usage.meter_name
    token_mapping: tokenMap(billing.usage.meter_name)
  # s223-m01 (#2527 ruling 4): quantities read grouped (86,420).
  included_quantity:
    semantic_type: billing.usage.included_quantity
    token_mapping: tokenMap(billing.usage.included_quantity)
    ui_hints:
      format: quantity
  consumed_quantity:
    semantic_type: billing.usage.consumed_quantity
    token_mapping: tokenMap(billing.usage.consumed_quantity)
    ui_hints:
      format: quantity
  unit_label:
    semantic_type: billing.usage.unit_label
    token_mapping: tokenMap(billing.usage.unit_label)
  period_start:
    semantic_type: billing.usage.period_start
    token_mapping: tokenMap(billing.usage.period_start)
  period_end:
    semantic_type: billing.usage.period_end
    token_mapping: tokenMap(billing.usage.period_end)
  rollover_strategy:
    semantic_type: billing.usage.rollover_strategy
    token_mapping: tokenMap(billing.usage.rollover_strategy)
  overage_rate_minor:
    semantic_type: billing.usage.overage_rate_minor
    token_mapping: tokenMap(billing.usage.overage_rate_minor)
    ui_hints:
      component: CurrencyAmount
      currencyField: currency
      minorUnits: 100
  projected_overage_minor:
    semantic_type: billing.usage.projected_overage_minor
    token_mapping: tokenMap(billing.usage.projected_overage_minor)
    ui_hints:
      component: CurrencyAmount
      currencyField: currency
      minorUnits: 100
  samples:
    semantic_type: billing.usage.samples
    token_mapping: tokenMap(billing.usage.samples)

tokens:
  billing.usage.meter_name: "var(--cmp-text-strong)"
  billing.usage.consumed_quantity: "var(--cmp-text-accent)"
  billing.usage.projected_overage_minor: "var(--cmp-text-warning)"

metadata:
  owners:
    - product-analytics@oods.systems
  maturity: beta
  references:
    - R13.5 Canonical Model: Subscription and Invoice