[HUME]
Start free

Catalog vs plans

The most common source of confusion in HUME billing is mixing up the tenant catalog (what exists) with a plan (what a subscriber gets and pays). They are separate layers. Reusing a metric on multiple plans does not copy quotas or prices between them.

One-line model: catalog = what you measure; plan = how much you include and what you charge on that tariff.

Two layers

LayerWhat it storesScope
Tenant catalogMetric and feature definitions (code, name, unit)One catalog per tenant — shared across all plans
PlanBase fee, per-metric pricing, groups, classify, limits, feature bindingsEach plan has its own copy of the rules — independent of other plans

Metrics

Catalog metric (POST /metrics)

Creates a billable meter once. The catalog record has no included_units, overage, or tiers — only identity:

json
POST /metrics
{
  "code": "api_requests",
  "name": "API Requests",
  "unit": "request"
}

Plan binding (POST /plans or POST /pricing/packages)

Attaches that meter to a specific plan with pricing for that plan only. The low-level API references the catalog by metric_id:

json
POST /plans
{
  "code": "pro",
  "name": "Pro",
  "monthly_price": 5000,
  "metrics": [
    {
      "metric_id": "met_01J8ZK5BQY8XQ9R2M4V7W3N6T1",
      "included_units": 100000,
      "overage_unit_price": 1
    }
  ]
}

POST /pricing/packages can create catalog metrics inline (compact or verbose format) and set plan pricing in one request — useful for a single plan. Bootstrap and multi-plan setups still create shared catalog entries once, then bind different included / overage on each plan.

Same metric, different quotas

This is intentional. One api_requests meter in the catalog; each plan sets its own included bucket and rates:

json
{
  "plans": [
    {
      "code": "starter",
      "price": 0,
      "metrics": {
        "api_requests": { "included": 1000, "overage": 2 }
      }
    },
    {
      "code": "pro",
      "price": 5000,
      "metrics": {
        "api_requests": { "included": 100000, "overage": 1 }
      }
    },
    {
      "code": "enterprise",
      "price": 20000,
      "metrics": {
        "api_requests": { "included": 1000000, "overage": 1 }
      }
    }
  ]
}

Changing included units on Pro does not change Starter. Subscribers are billed against the plan they are on, not against a global quota on the metric.

Features

The same split applies to entitlements:

Catalog (POST /features)Plan binding
code, name — the entitlement exists in the tenantWhich features this plan grants (enabled, optional effective_from)

exports can be on Pro and Enterprise but not Starter — each plan lists its own feature bindings. Check access with POST /entitlements/check against the user's active plan.

Plan-only constructs

These never live in the tenant catalog. They are defined per plan:

  • monthly_price, billing_interval, minimum charge, commitment, rollover, seat pricing
  • metric_groups[] — shared included / group pricing across member metrics
  • classify, limits[] — ingest routing and hard caps
  • Per-metric included_units, tiers, stairstep, aggregation on the plan binding

Two plans can both use api_requests from the catalog but only Pro might define a tokens metric group or classify routes — Starter stays simple.

Common misconceptions

AssumptionReality
Adding a metric to another plan copies its included unitsNo — you configure pricing again on that plan (or leave defaults such as 0 included until you set them)
included_units is stored on the metric in the catalogNo — it lives on the plan–metric binding (PlanMetric)
Editing a plan changes all plans that use the same metric codeNo — plans are edited independently (PUT /plans/{id} or package publish for that plan)
Quota groups are shared across plansNo — metric_groups are part of the plan JSON; Pro and Enterprise each define their own groups
Deleting a catalog metric removes it from plans automaticallyNo — DELETE /metrics/{id} returns 400 while any plan still references it

Typical workflow

  1. Create metrics and features in the catalog (or inline on first plan via /pricing/packages)
  2. Create plans and bind catalog entities with plan-specific pricing
  3. Subscribe users to a plan — usage and entitlements evaluate against that plan's rules
  4. Add a new tier (e.g. Business) — reuse catalog codes, set new included/overage/groups on the new plan only

Billing rule editor

In the dashboard editor, Tenant metrics / Tenant features list catalog entries not yet on the open plan. Adding one copies identity onto the plan; you then set included units, groups, and limits for this plan only. Saving the plan does not alter other plans that share the same metric code.