API Reference

Meters

Meters are used to track usage events for credit-based billing. You can create meters to represent specific billable actions or resources, and then record events against them. This allows you to implement usage-based pricing models where customers are billed based on their consumption.
For a practical guide on implementing credit billing, see the Credit Billing Guide.
The Meter Object#A Meter object contains all the information about a specific usage meter.
Attribute
Type
Description
id
string
Unique identifier for the meter.
object
string
The type of object, always "meter".
name
string
The name of the meter, which is displayed to the user.
event_name
string
A unique name for the event that this meter tracks. This is used when reporting usage.
aggregation_method
string
Specifies how usage events are aggregated. Can be sum, count, or last.
status
string
The current status of the meter. Can be active or inactive.
unit
string
The unit of measurement for the usage (e.g., requests, gb_hours).
description
string
An optional description of the meter.
livemode
boolean
true if the meter is in live mode, false if it is in test mode.
currency_id
string
The ID of the currency associated with this meter, if applicable.
metadata
object
A set of key-value pairs that you can attach to an object.
created_at
date
The timestamp when the meter was created.
updated_at
date
The timestamp when the meter was last updated.
paymentCurrency
object
An expanded object containing details about the associated currency. Present only when currency_id is set.
paymentCurrency Object#Attribute
Type
Description
id
string
Unique identifier for the currency.
name
string
The full name of the currency (e.g., "US Dollar").
symbol
string
The symbol for the currency (e.g., "$").
decimal
number
The number of decimal places for the currency.
type
string
The type of currency.
Create a Meter#Creates a new meter to track a specific type of usage.
Parameters
Name
Type
Description
name
string
Required. The display name for the meter.
event_name
string
Required. A unique machine-readable name for the event being tracked.
unit
string
Required. The unit of measurement for the usage.
aggregation_method
'sum' | 'count' | 'last'
The method for aggregating usage data. Defaults to sum.
currency_id
string
The ID of an existing currency to associate with this meter.
description
string
An optional description for the meter.
metadata
Record<string, any>
An optional set of key-value pairs for additional information.
Returns
Returns the newly created Meter object.
Example
async function createMeter() {
  try {
    const meter = await payment.meters.create({
      name: 'API Calls',
      event_name: 'api.calls.count',
      unit: 'call',
      aggregation_method: 'count',
      description: 'Counts the number of API calls made.'
    });
    console.log('Meter created:', meter);
  } catch (error) {
    console.error('Error creating meter:', error);
  }
}

createMeter();Example Response
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "active",
  "unit": "call",
  "description": "Counts the number of API calls made.",
  "livemode": false,
  "metadata": {},
  "currency_id": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Retrieve a Meter#Retrieves the details of an existing meter by its unique ID.
Parameters
Name
Type
Description
id
string
Required. The ID of the meter to retrieve.
Returns
Returns the Meter object if found.
Example
async function retrieveMeter(meterId) {
  try {
    const meter = await payment.meters.retrieve(meterId);
    console.log('Retrieved meter:', meter);
  } catch (error) {
    console.error('Error retrieving meter:', error);
  }
}

retrieveMeter('mtr_1234567890');Example Response
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "active",
  "unit": "call",
  "description": "Counts the number of API calls made.",
  "livemode": false,
  "metadata": {},
  "currency_id": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}Update a Meter#Updates an existing meter's information.
Parameters
Name
Type
Description
id
string
Required. The ID of the meter to update.
data
object
Required. An object containing the fields to update.
data.name
string
The new name for the meter.
data.description
string
The new description for the meter.
data.status
'active' | 'inactive'
The new status for the meter.
data.metadata
Record<string, any>
A set of key-value pairs to update.
Returns
Returns the updated Meter object.
Example
async function updateMeter(meterId) {
  try {
    const meter = await payment.meters.update(meterId, {
      description: 'Total number of API calls made by a customer.',
      metadata: { 'version': '2.0' }
    });
    console.log('Updated meter:', meter);
  } catch (error) {
    console.error('Error updating meter:', error);
  }
}

updateMeter('mtr_1234567890');Example Response
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "active",
  "unit": "call",
  "description": "Total number of API calls made by a customer.",
  "livemode": false,
  "metadata": {
    "version": "2.0"
  },
  "currency_id": null,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:05:00.000Z"
}List all Meters#Returns a paginated list of all meters. You can filter the list using the provided parameters.
Parameters
Name
Type
Description
event_name
string
Filter meters by a specific event name.
livemode
boolean
Filter meters by their live mode status.
q
string
A query string for searching across meter fields like name and description.
page
number
The page number for pagination.
pageSize
number
The number of items to return per page. Defaults to 20.
order
string | string[]
The order to sort the results by. Example: ['created_at', 'DESC'].
Returns
Returns a paginated object containing a list of Meter objects and a count of the total number of meters.
Example
async function listMeters() {
  try {
    const meters = await payment.meters.list({ pageSize: 5 });
    console.log(`Found ${meters.count} meters.`);
    console.log('First page of meters:', meters.list);
  } catch (error) {
    console.error('Error listing meters:', error);
  }
}

listMeters();Example Response
{
  "count": 15,
  "list": [
    {
      "id": "mtr_1234567890",
      "object": "meter",
      "name": "API Calls",
      "event_name": "api.calls.count",
      "aggregation_method": "count",
      "status": "active",
      "unit": "call",
      "description": "Total number of API calls made by a customer.",
      "livemode": false,
      "metadata": {
        "version": "2.0"
      },
      "currency_id": null,
      "created_at": "2023-10-27T10:00:00.000Z",
      "updated_at": "2023-10-27T10:05:00.000Z"
    }
  ]
}Activate a Meter#Sets a meter's status to active. Active meters can be used to record usage events.
Parameters
Name
Type
Description
id
string
Required. The ID of the meter to activate.
Returns
Returns the Meter object with its status updated to active.
Example
async function activateMeter(meterId) {
  try {
    const meter = await payment.meters.activate(meterId);
    console.log('Meter activated:', meter.status);
  } catch (error) {
    console.error('Error activating meter:', error);
  }
}

activateMeter('mtr_0987654321');Example Response
{
  "id": "mtr_0987654321",
  "object": "meter",
  "name": "Data Storage",
  "event_name": "data.storage.gb",
  "aggregation_method": "last",
  "status": "active",
  "unit": "gb",
  "livemode": false,
  // ... other attributes
}Deactivate a Meter#Sets a meter's status to inactive. Inactive meters cannot be used to record new usage events.
Parameters
Name
Type
Description
id
string
Required. The ID of the meter to deactivate.
Returns
Returns the Meter object with its status updated to inactive.
Example
async function deactivateMeter(meterId) {
  try {
    const meter = await payment.meters.deactivate(meterId);
    console.log('Meter deactivated:', meter.status);
  } catch (error) {
    console.error('Error deactivating meter:', error);
  }
}

deactivateMeter('mtr_1234567890');Example Response
{
  "id": "mtr_1234567890",
  "object": "meter",
  "name": "API Calls",
  "event_name": "api.calls.count",
  "aggregation_method": "count",
  "status": "inactive",
  "unit": "call",
  "livemode": false,
  // ... other attributes
}
Now that you know how to manage meters, the next step is to report usage against them. Proceed to the Meter Events API reference to learn how.

Attribute	Type	Description
`id`	`string`	Unique identifier for the meter.
`object`	`string`	The type of object, always `"meter"`.
`name`	`string`	The name of the meter, which is displayed to the user.
`event_name`	`string`	A unique name for the event that this meter tracks. This is used when reporting usage.
`aggregation_method`	`string`	Specifies how usage events are aggregated. Can be `sum`, `count`, or `last`.
`status`	`string`	The current status of the meter. Can be `active` or `inactive`.
`unit`	`string`	The unit of measurement for the usage (e.g., `requests`, `gb_hours`).
`description`	`string`	An optional description of the meter.
`livemode`	`boolean`	`true` if the meter is in live mode, `false` if it is in test mode.
`currency_id`	`string`	The ID of the currency associated with this meter, if applicable.
`metadata`	`object`	A set of key-value pairs that you can attach to an object.
`created_at`	`date`	The timestamp when the meter was created.
`updated_at`	`date`	The timestamp when the meter was last updated.
`paymentCurrency`	`object`	An expanded object containing details about the associated currency. Present only when `currency_id` is set.

Attribute	Type	Description
`id`	`string`	Unique identifier for the currency.
`name`	`string`	The full name of the currency (e.g., "US Dollar").
`symbol`	`string`	The symbol for the currency (e.g., "$").
`decimal`	`number`	The number of decimal places for the currency.
`type`	`string`	The type of currency.

Name	Type	Description
`name`	`string`	Required. The display name for the meter.
`event_name`	`string`	Required. A unique machine-readable name for the event being tracked.
`unit`	`string`	Required. The unit of measurement for the usage.
`aggregation_method`	`'sum' \| 'count' \| 'last'`	The method for aggregating usage data. Defaults to `sum`.
`currency_id`	`string`	The ID of an existing currency to associate with this meter.
`description`	`string`	An optional description for the meter.
`metadata`	`Record<string, any>`	An optional set of key-value pairs for additional information.

Name	Type	Description
`id`	`string`	Required. The ID of the meter to update.
`data`	`object`	Required. An object containing the fields to update.
`data.name`	`string`	The new name for the meter.
`data.description`	`string`	The new description for the meter.
`data.status`	`'active' \| 'inactive'`	The new status for the meter.
`data.metadata`	`Record<string, any>`	A set of key-value pairs to update.

Name	Type	Description
`event_name`	`string`	Filter meters by a specific event name.
`livemode`	`boolean`	Filter meters by their live mode status.
`q`	`string`	A query string for searching across meter fields like `name` and `description`.
`page`	`number`	The page number for pagination.
`pageSize`	`number`	The number of items to return per page. Defaults to 20.
`order`	`string \| string[]`	The order to sort the results by. Example: `['created_at', 'DESC']`.

Overview

Get Started

Core Concepts

Usage Guides

API Reference

TypeScript Support

Meters

The Meter Object#

paymentCurrency Object#

Create a Meter#

Retrieve a Meter#

Update a Meter#

List all Meters#

Activate a Meter#

Deactivate a Meter#

Settings

Meter Events