Metered Billing

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

const plan = await paybridgenp.plans.create({
  name: "API calls",
  amount: 50,                    // unit price: 50 paisa per call
  intervalUnit: "month",
  billingScheme: "metered",
  aggregationMethod: "sum",      // sum | max | last_ever
});

billingScheme is set at creation and cannot be changed afterwards - switching a plan between per_unit and metered under live subscriptions would change what their invoices bill. Create a new plan instead.

A metered plan is defined by two settings:

billingScheme: "metered" - bill on reported usage instead of a flat price
aggregationMethod - how usage is combined over the billing period:
- sum - total usage across all records in the period (default)
- max - the single highest usage value reported (useful for high-water-mark billing)
- last_ever - the most recent value ever reported

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

Report usage

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

await paybridgenp.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 paybridgenp.subscriptions.getUsageSummary(subscriptionId);
// { quantity: 1500, record_count: 15, aggregation_method: "sum", period_start, period_end }

How invoicing works

At the end of each billing period, PayBridgeNP:

Aggregates all usage records for the period using the plan’s aggregationMethod
Multiplies the result by the plan’s amount (unit price)
Generates an invoice for that total
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 paybridgenp.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 paybridgenp.subscriptions.create({
  customerId,
  planId: plan.id,
  quantity: 5,              // 5 seats = Rs. 7,495/month
});

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

Getting started

Accepting payments

Checkout

Providers

Subscriptions and billing

Branding

Operations

Integrations

Create a metered plan

Report usage

Check current usage

How invoicing works

Per-seat billing