Metered Billing

Charge customers based on actual usage with metered plans.

Metered billing lets you charge customers based on what they consume in a billing period - API calls, active seats, storage used, or any other unit you define. At the end of each period, PayBridgeNP aggregates the usage records and issues an invoice for the accumulated amount.

Create a metered plan

Set billingScheme to "metered" and choose an aggregationMethod:

• sum - total usage across all records in the period (default)
• max - the single highest usage value reported
• last_ever - the most recent value ever reported (useful for high-water-mark billing)

The plan amount is the unit price in paisa. The invoice is amount × aggregated_quantity.

const plan = await paybridge.billing.plans.create({
  name: "API Calls",
  amount: 10,               // Rs. 0.10 per call
  intervalUnit: "month",
  billingScheme: "metered",
  aggregationMethod: "sum",
});

Report usage

Call reportUsage after each usage event, or batch at intervals:

await paybridge.billing.subscriptions.reportUsage(subscriptionId, {
  quantity: 100,            // number of units consumed
  action: "increment",      // "increment" (default) or "set"
  idempotencyKey: "evt_abc123", // prevents double-counting on retry
});

Use action: "set" to report the absolute current value instead of adding to the running total (useful with max or last_ever aggregation).

Check current usage

const summary = await paybridge.billing.subscriptions.getUsageSummary(subscriptionId);
// { quantity: 1500, recordCount: 15, aggregationMethod: "sum", periodStart, periodEnd }

How invoicing works

At the end of each billing period, PayBridgeNP:

1. Aggregates all usage records for the period using the plan’s aggregationMethod
2. Multiplies the result by the plan’s amount (unit price)
3. Generates an invoice for that total
4. Resets the usage counter for the next period

If no usage was reported in a period, a zero-amount invoice is generated and immediately marked as paid.

Per-seat billing

For per-seat (quantity-based) billing where you charge a flat rate multiplied by the number of seats, use billingScheme: "per_unit" (the default) and update the quantity when seats change:

// Create per-unit plan
const plan = await paybridge.billing.plans.create({
  name: "Team Plan",
  amount: 149900,           // Rs. 1,499 per seat per month
  intervalUnit: "month",
  // billingScheme: "per_unit" is the default
});

// Create subscription with initial seat count
const sub = await paybridge.billing.subscriptions.create({
  customerId,
  planId: plan.id,
  quantity: 5,              // 5 seats = Rs. 7,495/month
});

// Update when seats change
await paybridge.billing.subscriptions.updateQuantity(sub.id, 8);