Usage

Pour les plans à l’usage (metered, tiered, credit…), vous déclarez ce que chaque abonnement consomme. Ce guide couvre l’enregistrement, l’idempotence, la lecture et les seuils. Les exemples utilisent une clé qb_test_sk_….

Enregistrer un usage

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

Corps : subscription, metric_name, quantity, et en option idempotency_key. Avec le SDK Node (bientôt sur npm) :

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

Idempotence

Donnez à chaque événement son propre idempotency_key. La clé vaut par abonnement : renvoyer la même clé pour le même abonnement ne compte qu’une fois, donc vous pouvez réessayer un appel qui a expiré sans compter deux fois.

Lire l’usage

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

Avec le SDK : qbill.usage.summary({ subscription }). Il renvoie ce que l’abonnement a consommé dans sa période en cours, par métrique.

Seuils

Un plan peut déclarer des limits, un nombre par métrique. Quand un abonnement atteint 80 % puis 100 % de limits[metric], QBill envoie l’événement usage.threshold_reached, une fois par seuil et par période. Son data :

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

C’est un avertissement, pas un plafond : l’usage au-delà de la limite est quand même enregistré. Les unités gratuites et le dépassement sont des réglages du plan, voir Clients, plans, abonnements. La livraison des webhooks est décrite dans Webhooks.