Metering

Use this page to enforce usage-based limits through assigned license features and the runtime consume route.

Who This Is For

• teams shipping usage-based or credit-based licensing
• developers implementing feature quotas
• operators who need usage evidence for reporting and exports

When To Use This

Use metering when the primary control is consumed usage, not just time or device count.

Metering is layered on top of feature assignments. It is not a billing engine by itself.

How It Works

The metering flow is:

1. create a feature on the product
2. assign that feature to a license
3. optionally set max_consumptions
4. call POST /api/v1/license/consume at runtime
5. use POST /api/v1/licenses/{id}/usage/reset to reset or top up usage

Important rules:

• consume uses runtime license auth
• consume requires Idempotency-Key
• usage reset is a management route
• reporting reads and exports are the downstream evidence surface for consumed usage

Example

Assign a metered feature:

curl -X POST https://api.licensekit.dev/api/v1/licenses/lic_123/features \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "feature_id": "feat_api_calls",
    "max_consumptions": 1000
  }'

Consume one unit:

curl -X POST https://api.licensekit.dev/api/v1/license/consume \
  -H "Authorization: License $LICENSE_KEY" \
  -H "Idempotency-Key: consume-evt-123" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "workstation-01",
    "feature_code": "api_calls",
    "amount": 1,
    "event_id": "evt_123"
  }'

Common Mistakes

• assuming consumption license type alone creates quotas without feature assignments
• forgetting Idempotency-Key on the runtime consume route
• treating metering as a billing engine instead of entitlement enforcement plus evidence
• using live totals as a substitute for the reporting ledger when period-aware evidence matters

Related Pages

• Usage Summary
• Usage Ledger
• Licensing Models