Plan extensions

POST /pricing/packages and POST /plans accept the same optional plan-level fields. Without pricing_lua, built-in logic handles invoicing and JSON classify at ingest. For copy-paste scenarios by use case, start with Recipes. Luau escape hatch: Pricing → Luau.

JSON vs Luau

JSON and Luau can coexist: JSON classify runs first at ingest, then Luau classify. Invoicing uses Luau pricing when present; otherwise JSON billing applies.

Usage ingest pipeline

When a subscribed user records usage (POST /usage, StatsD, usage.recorded):

1. JSON classify — classify.routes may reroute the metric (first match wins)
2. JSON reject — classify.reject may return 400
3. JSON limits — limits[] with action: reject may return 400
4. Luau classify — runs last if the plan defines a classify function

The stored usage event contains the final metric after all steps.

Per-metric fields

On each entry in metrics[] (packages create catalog metrics; plans bind by metric_id):

Classify and ingest limits always use sum semantics, regardless of aggregation.

Metric groups

Share one included quota (and optional group-level tiers) across several metrics:

{
  "code": "tokens",
  "metric_codes": ["tokens_peak", "tokens_offpeak"],
  "included_units": 1000000,
  "overage_unit_price": 2,
  "tiers": [{"from": 1000001, "to": null, "price_per_unit": 1}]
}

• code — group id (referenced in classify.reject and limits)
• Each metric_codes entry must appear in metrics[]
• A metric cannot be in both a group and usage_pool
• Without group-level tiers/overage: included is consumed member-by-member; each member's excess uses that metric's own rates

JSON classify

Route or reject usage at ingest without Luau. Each route matches on the incoming metric plus optional filters — all set fields combine with AND. First matching route wins.

{
  "routes": [
    {"when": {"metric": "tokens"}, "if": {"hour_local": [9, 18], "weekdays_local": [1, 2, 3, 4, 5]}, "to": "tokens_peak"},
    {"when": {"metric": "api_requests", "quantity_gte": 500}, "to": "api_requests_bulk"},
    {"when": {"metric": "tokens", "period_usage_gte": 1000000}, "to": "tokens_bulk"},
    {"when": {"metric": "tokens"}, "to": "tokens_offpeak"}
  ],
  "reject": [
    {"when": {"group": "tokens", "period_usage_plus_qty_gt": 1000000}, "reason": "monthly cap exceeded"}
  ]
}

Equivalent Luau examples: Luau classify ctx.

Ingest limits

{
  "scope": "metric_group",
  "group": "tokens",
  "max_per_period": 1000000,
  "action": "reject"
}

scope is metric (requires metric_code) or metric_group (requires group). Only action: reject is supported. Counts total usage in the current subscription period.

Stairstep pricing

On a metric, set pricing_model: "stairstep" with block_size and block_price:

{
  "metric_code": "api_requests",
  "metric_name": "API Requests",
  "metric_unit": "request",
  "included_units": 0,
  "pricing_model": "stairstep",
  "block_size": 1000,
  "block_price": 500
}

2500 units → 3 blocks × 500 = 1500. included_units are free before block counting starts. Cannot combine with tiers or overage_unit_price.

Usage pool

Simpler than groups when metrics are interchangeable — one shared included bucket:

{
  "usage_pool": {
    "metric_codes": ["api_requests", "exports_rows"],
    "included_units": 10000
  }
}

After the pool is exhausted, each metric's own overage or tiers apply to its billable portion.

SaaS billing blocks

Invoice calculation order

For plans without Luau pricing:

1. Base fee (prorated; annual interval if configured)
2. Metric groups — shared included, then group tiers/overage or per-member rates
3. Usage pool — shared included, then per-member rates
4. Individual metrics not in a group or pool
5. Seat pricing
6. Minimum charge and commitment top-up lines

Luau pricing(ctx) replaces all of the above for that plan segment when present.

Validation

POST /plans and POST /pricing/packages return 400 when:

• a metric appears in both metric_groups and usage_pool
• a metric or group uses both tiers and overage_unit_price
• stairstep is combined with tiers or overage_unit_price
• classify.routes[].to references an unknown metric
• billing_interval is not month or year

Examples

Peak / off-peak with shared quota

Clients send usage on generic tokens. Ingest routes to peak/off-peak meters; invoice bills the shared group pool, then per-metric overage rates.

Growth plan with pool, stairstep, seats, and rollover

{
  "code": "growth",
  "name": "Growth",
  "monthly_price": 5000,
  "minimum_monthly_charge": 10000,
  "billing_interval": "month",
  "included_rollover": {"max_periods": 1, "cap_units": 50000},
  "usage_pool": {
    "metric_codes": ["api_requests", "exports_rows"],
    "included_units": 10000
  },
  "metrics": [
    {
      "metric_code": "api_requests",
      "metric_name": "API Requests",
      "metric_unit": "request",
      "pricing_model": "stairstep",
      "block_size": 1000,
      "block_price": 500
    },
    {
      "metric_code": "exports_rows",
      "metric_name": "Export rows",
      "metric_unit": "row",
      "overage_unit_price": 1
    }
  ],
  "commitment_units": {"metric_code": "api_requests", "min": 100000},
  "seat_pricing": {"included_seats": 10, "overage_per_seat": 800},
  "line_labels": {"base": "Growth platform fee", "overage": "API overage"}
}