Usage-based billing

Overview

Usage-based (metered) billing lets you charge customers based on actual consumption — API calls, seats, storage, or any unit you define.

1. Create a metered plan

Set billing_type to METERED and define price_per_unit:

curl -X POST https://api.paypulse.cv/api/v1/plans \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pp_test_xxxx" \
  -d '{
    "name": "API Usage",
    "price_per_unit": 0.01,
    "unit_label": "API call",
    "currency": "NGN",
    "interval": "MONTHLY"
  }'

2. Report usage

As your customers consume units, report them via the API:

curl -X POST https://api.paypulse.cv/api/v1/subscriptions/{sub_id}/usage \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: pp_test_xxxx" \
  -d '{
    "quantity": 15000,
    "description": "January API calls",
    "idempotency_key": "usage_2026_01_api_calls"
  }'

Usage records are append-only. The same idempotency_key will not be recorded twice.

3. Check current usage

See what’s unbilled for the current period:

curl https://api.paypulse.cv/api/v1/subscriptions/{sub_id}/usage \
  -H "X-Api-Key: pp_test_xxxx"

4. Billing

At the end of each billing period, the ARQ worker automatically:

Sums all unbilled usage records
Creates an invoice for total_quantity × price_per_unit
Attempts to charge the customer
Marks the usage records as billed

Idempotency

Each usage report requires a unique idempotency_key. If you send the same key twice, the second request returns created: false without duplicating the record. Best practice: use a deterministic key like {subscription_id}_{date}_{event_type}.

​Overview

​1. Create a metered plan

​2. Report usage

​3. Check current usage

​4. Billing

​Idempotency

Overview

1. Create a metered plan

2. Report usage

3. Check current usage

4. Billing

Idempotency