Recipes

Pick the scenario closest to yours, copy the plan payload into POST /pricing/packages, then follow Quickstart for tenant → subscription → usage → invoice. All amounts are integers in abstract billing units (map to cents, credits, etc. in your app).

Which recipe?

Three questions:

1. Meter usage? No → flat monthly. Yes → continue.
2. One SDK counter, several billable meters? (peak/off-peak, bulk vs standard) → peak / off-peak or Luau classify.
3. Custom invoice math JSON can't express? → Luau pricing. Otherwise stay in JSON — start simple, add fields as needed.

Level 1 — flat fee and simple metering

No extensions, no Luau. Good first integration.

Flat monthly SaaS

Scenario: Notion-style — pay monthly, no usage meter. Maybe gate UI features.

• You send: nothing at ingest (or optional entitlement checks)
• Invoice: prorated monthly_price only

{
  "code": "pro",
  "name": "Pro",
  "monthly_price": 2900,
  "metrics": [],
  "features": [
    {"feature_code": "dashboard", "feature_name": "Dashboard", "enabled": true}
  ]
}

After creating the plan: POST /subscriptions, then POST /invoices/generate.

Freemium API

Scenario: 1000 free API requests per month, then $0.02 per extra request (stored as overage_unit_price: 2 in abstract units).

• You send: POST /usage or StatsD on each API call
• Invoice: base fee (0 here) + overage line for usage above 1000

{
  "code": "starter",
  "name": "Starter",
  "monthly_price": 0,
  "metrics": [{
    "metric_code": "api_requests",
    "metric_name": "API Requests",
    "metric_unit": "request",
    "included_units": 1000,
    "overage_unit_price": 2
  }]
}

Feature gate

Scenario: Starter has API access; Pro adds CSV exports. Your app checks before showing the export button.

• Add features[] to any plan payload (see flat monthly example)
• Before export: POST /entitlements/check with feature_code: "exports"

Combine with freemium or flat monthly — features and metrics are independent.

Level 2 — tiers, seats, shared quota

Volume tiers

Scenario: Included 500 requests, then $0.03/unit until 10k, then $0.01/unit above that.

• You send: same as freemium — one api_requests counter
• Invoice: built-in graduated tier math

{
  "code": "growth",
  "name": "Growth",
  "monthly_price": 4900,
  "metrics": [{
    "metric_code": "api_requests",
    "metric_name": "API Requests",
    "metric_unit": "request",
    "included_units": 500,
    "tiers": [
      {"from": 501, "to": 10000, "price_per_unit": 3},
      {"from": 10001, "to": null, "price_per_unit": 1}
    ]
  }]
}

Per-seat pricing

Scenario: Team plan includes 5 seats, each extra seat $12/mo. HUME tracks active users automatically via monthly_tracked_users when users trigger metering or entitlement checks.

• You send: usage events or entitlement checks (first event per user per month counts as 1 seat)
• Invoice: seat line from seat_pricing

{
  "code": "team",
  "name": "Team",
  "monthly_price": 0,
  "seat_pricing": {
    "included_seats": 5,
    "overage_per_seat": 1200
  },
  "metrics": []
}

Details: Pricing → MTU.

Shared quota (usage pool)

Scenario: Pro includes 10k combined API calls or export rows — whichever the customer uses first.

• You send: api_requests and exports_rows separately
• Invoice: pool consumed first, then each metric's overage rate applies

{
  "code": "pro",
  "name": "Pro",
  "monthly_price": 1900,
  "usage_pool": {
    "metric_codes": ["api_requests", "exports_rows"],
    "included_units": 10000
  },
  "metrics": [
    {"metric_code": "api_requests", "metric_name": "API Requests", "metric_unit": "request", "included_units": 0, "overage_unit_price": 2},
    {"metric_code": "exports_rows", "metric_name": "Export rows", "metric_unit": "row", "included_units": 0, "overage_unit_price": 1}
  ]
}

Level 3 — routing, caps, SaaS blocks

Peak / off-peak tokens

Scenario: LLM API — SDK always reports tokens. Business hours bill at $0.03, nights/weekends at $0.01. Shared 1M token included allowance across both meters.

• You send: tokens only — classify reroutes at ingest
• Invoice: group shared included, then per-meter overage rates

{
  "code": "llm",
  "name": "LLM API",
  "monthly_price": 5000,
  "metrics": [
    {"metric_code": "tokens", "metric_name": "Tokens", "metric_unit": "token", "included_units": 0},
    {"metric_code": "tokens_peak", "metric_name": "Peak tokens", "metric_unit": "token", "included_units": 0, "overage_unit_price": 3},
    {"metric_code": "tokens_offpeak", "metric_name": "Off-peak tokens", "metric_unit": "token", "included_units": 0, "overage_unit_price": 1}
  ],
  "metric_groups": [{
    "code": "tokens",
    "metric_codes": ["tokens_peak", "tokens_offpeak"],
    "included_units": 1000000
  }],
  "classify": {
    "routes": [
      {"when": {"metric": "tokens"}, "if": {"hour_utc": [9, 18]}, "to": "tokens_peak"},
      {"when": {"metric": "tokens"}, "to": "tokens_offpeak"}
    ]
  }
}

Luau equivalent: classify examples.

Hard cap at ingest

Scenario: Free plan allows 100 API calls per billing period — reject request #101 with 400 so your app can show an upgrade modal immediately.

• You send: usage as usual
• Ingest: limits[] rejects before the event is stored

{
  "code": "free",
  "name": "Free",
  "monthly_price": 0,
  "metrics": [{
    "metric_code": "api_requests",
    "metric_name": "API Requests",
    "metric_unit": "request",
    "included_units": 100
  }],
  "limits": [{
    "scope": "metric",
    "metric_code": "api_requests",
    "max_per_period": 100,
    "action": "reject"
  }]
}

Stairstep (block pricing)

Scenario: Batch API — $5 per 1000 requests, rounded up. 2500 calls → 3 blocks → $15.

• You send: total requests per event or aggregated via StatsD
• Invoice: block count × block_price

{
  "code": "batch",
  "name": "Batch API",
  "monthly_price": 0,
  "metrics": [{
    "metric_code": "api_requests",
    "metric_name": "API Requests",
    "metric_unit": "request",
    "included_units": 0,
    "pricing_model": "stairstep",
    "block_size": 1000,
    "block_price": 500
  }]
}

Minimum charge & usage commitment

Scenario: Enterprise commits to at least $500/mo and 100k API calls — charge shortfall if they use less.

• Invoice: usage lines + top-up to minimum_monthly_charge + commitment shortfall line

{
  "code": "enterprise",
  "name": "Enterprise",
  "monthly_price": 0,
  "minimum_monthly_charge": 50000,
  "commitment_units": {"metric_code": "api_requests", "min": 100000},
  "metrics": [{
    "metric_code": "api_requests",
    "metric_name": "API Requests",
    "metric_unit": "request",
    "included_units": 0,
    "overage_unit_price": 1
  }]
}

Also available: included_rollover for unused quota credit — Plan extensions.

Annual billing

Scenario: Same as Pro but billed yearly with 20% discount on the base fee.

{
  "code": "pro_annual",
  "name": "Pro Annual",
  "monthly_price": 2900,
  "billing_interval": "year",
  "annual_discount_percent": 20,
  "metrics": [{
    "metric_code": "api_requests",
    "metric_name": "API Requests",
    "metric_unit": "request",
    "included_units": 50000,
    "overage_unit_price": 1
  }]
}

Level 4 — Luau when JSON is not enough

Custom pricing or classify

Reach for Luau when:

• Progressive discount curves not expressible as tiers (e.g. first 1000 overage at one rate, rest at another — see pricing examples)
• Route usage by quantity per event (bulk batches → separate meter)
• Cross-metric formulas on one invoice line
• Fully custom line item descriptions and amounts

Pass a Luau script as pricing_lua on POST /pricing/packages. JSON extensions and Luau can coexist — JSON classify runs first, then Luau. See Pricing → Luau and ingest pipeline.

After you pick a recipe

1. POST /pricing/packages with the JSON body (add Idempotency-Key)
2. POST /users — create a billable user
3. POST /subscriptions — attach user to plan
4. Send usage: POST /usage or StatsD
5. POST /invoices/generate — get line items for your payment provider
6. Optional: webhooks for subscription.* and invoice.generated

Full curl walkthrough: Quickstart.