Meters

Overview

A meter is a named counter that tracks a specific type of usage event. Meters aggregate reported events over each billing period and feed into usage-based plans.

Create a meter

const meter = await xtopay.meters.create({
  name: "sms_sent",
  display_name: "SMS Messages Sent",
  event_name: "sms.sent",         // events with this name are counted
  aggregation: "count",           // "count" | "sum" | "max" | "last"
  value_field: null,              // required for "sum" / "max" / "last"
  reset_interval: "billing_period", // reset usage at start of each billing period
});

Aggregation types

Aggregation	Meaning	When to use
`count`	Count of events reported	API calls, logins, SMS sent
`sum`	Sum of a numeric field across events	Data egress in MB, compute minutes
`max`	Highest value seen across events	Peak concurrent users, peak storage
`last`	Most recent value	Current seat count

For sum, max, and last, specify the numeric field in the event payload:

const meter = await xtopay.meters.create({
  name: "storage_gb",
  event_name: "storage.snapshot",
  aggregation: "max",
  value_field: "gb_used",   // reads event.payload.gb_used
});

Meter object

{
  "id": "mtr_a1b2c3",
  "name": "api_calls",
  "display_name": "API Calls",
  "event_name": "api.request",
  "aggregation": "count",
  "reset_interval": "billing_period",
  "active": true,
  "created_at": "2026-01-01T00:00:00Z"
}

Checking current usage

const usage = await xtopay.meters.getUsage({
  meter_id: "mtr_a1b2c3",
  customer_id: "cus_abc123",
  // defaults to current billing period
});

console.log(usage.quantity);         // e.g. 4821
console.log(usage.period_start);     // "2026-05-01T00:00:00Z"
console.log(usage.period_end);       // "2026-06-01T00:00:00Z"

Tiered pricing

You can configure volume tiers on a plan that uses a meter:

const plan = await xtopay.plans.create({
  name: "API calls",
  currency: "GHS",
  interval: "month",
  billing_scheme: "tiered",
  meter_id: meter.id,
  tiers: [
    { up_to: 1000,    unit_amount: 0 },     // first 1,000 free
    { up_to: 10000,   unit_amount: 3 },     // GHS 0.03 each
    { up_to: "inf",   unit_amount: 2 },     // GHS 0.02 each above 10,000
  ],
  tiers_mode: "graduated",  // "graduated" | "volume"
});