Usage

For metered, tiered, credit and other usage-based plans, you report what each subscription consumes. This guide covers recording, idempotency, reading, and thresholds. Examples use a qb_test_sk_… key.

Recording usage

curl -X POST https://api.qbill.dev/v1/usage \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"subscription":"<subscription id>","metric_name":"api_calls","quantity":120,"idempotency_key":"batch-2026-10-04-01"}'

Body: subscription, metric_name, quantity, and optionally idempotency_key. With the Node SDK (coming to npm):

await qbill.usage.record({
  subscription: '<subscription id>',
  metric_name: 'api_calls',
  quantity: 120,
  idempotency_key: 'batch-2026-10-04-01',
});

Idempotency

Give each event its own idempotency_key. The key is scoped to the subscription: sending the same key again for the same subscription counts once, so you can retry a call that timed out without double counting.

Reading usage

curl "https://api.qbill.dev/v1/usage?subscription=<subscription id>" \
  -H "x-api-key: qb_test_sk_…"

With the SDK: qbill.usage.summary({ subscription }). It returns what the subscription has used in its current period, by metric.

Thresholds

A plan can declare limits, one number per metric. When a subscription reaches 80 % and then 100 % of limits[metric], QBill sends the usage.threshold_reached event, once per threshold and per period. Its data:

{
  "subscription_id": "…",
  "customer_id": "…",
  "metric": "api_calls",
  "threshold": 80,
  "used": 800,
  "limit": 1000,
  "period_end": "…"
}

It is a warning, not a cap: usage past the limit is still recorded. Free units and overage billing are plan settings, see Customers, plans, subscriptions. Webhook delivery is covered in Webhooks.