Usage Billing
Usage Billing
Meter any event and charge customers for exactly what they consume.
Overview
Usage-based billing lets you charge customers based on what they actually use — API calls, SMS sent, storage GB, seats active — rather than a flat monthly fee. Xtopay handles:
- Meters — define what you want to measure
- Usage events — your app reports events to Xtopay in real time
- Aggregation — Xtopay sums, counts, or takes the max over the billing period
- Billing — at period end, Xtopay calculates the charge and creates an invoice
How it works
Your app Xtopay
─────────────────────────────
Report event ──────→ Aggregated by meter
↓
At period end
↓
Calculate usage × rate
↓
Create invoice
↓
Charge customerQuick start
// 1. Create a meter
const meter = await xtopay.meters.create({
name: "api_calls",
aggregation: "count", // count every event
event_name: "api.request",
});
// 2. Create a usage-based plan
const plan = await xtopay.plans.create({
name: "Pay-as-you-go",
currency: "GHS",
interval: "month",
billing_scheme: "per_unit",
meter_id: meter.id,
unit_amount: 5, // GHS 0.05 per API call
free_units: 1000, // first 1,000 calls free
});
// 3. Report usage in real time
await xtopay.meters.reportEvent({
meter_id: meter.id,
customer_id: "cus_abc123",
event_name: "api.request",
timestamp: new Date().toISOString(),
quantity: 1,
});