Meters

Meters are used to define and track usage for credit-based billing. They represent a specific feature or resource that you bill for, such as API calls, data storage, or compute time. Each meter aggregates usage events sent to it.

Once a meter is created, you can report usage against it using Meter Events. This is a core component of implementing a Credit-Based Billing model.

The Meter Object#

A Meter object contains all the information about a specific usage tracker.

Attribute	Type	Description
id	string	Unique identifier for the meter.
name	string	The display name of the meter.
event_name	string	A unique name for the event this meter tracks. This is used when reporting usage.
aggregation_method	string	The method used to aggregate usage. Currently, only sum is supported.
unit	string	The unit of measurement for the usage (e.g., 'requests', 'gb', 'credits').
status	string	The current status of the meter. Can be active or inactive. Inactive meters do not accept new events.
livemode	boolean	true if the meter was created in live mode, false for test mode.
currency_id	string	The ID of the payment currency associated with this meter.
description	string	An optional description of the meter.
metadata	object	A set of key-value pairs that you can attach to an object. Useful for storing additional information.
paymentCurrency	object	The expanded payment currency object associated with the meter.

The paymentCurrency Object Properties

Attribute	Type	Description
id	string	Unique identifier for the currency.
name	string	The name of the currency (e.g., 'API Credits').
symbol	string	The symbol for the currency (e.g., 'AC').
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 usage of a specific feature.

Parameters

Attribute	Type	Description
name	string	Required. The display name of the meter. Maximum 64 characters.
event_name	string	Required. A unique name for the event this meter tracks. This is used when reporting usage. Maximum 64 characters.
unit	string	Required. The unit of measurement for the usage (e.g., 'requests', 'gb', 'credits'). Maximum 32 characters.
aggregation_method	string	Optional. The method to aggregate usage. Defaults to sum. Currently, this is the only supported value.
currency_id	string	Optional. The ID of the payment currency to associate with this meter. If not provided, a new credit currency will be created automatically.
description	string	Optional. A description of what this meter tracks. Maximum 255 characters.
metadata	object	Optional. A set of key-value pairs to store additional information about the meter.

Returns

Returns the newly created Meter object.

import payment from '@blocklet/payment-js';

async function createMeter() {
  try {
    const meter = await payment.meters.create({
      name: 'API Calls',
      event_name: 'api.calls.v1',
      unit: 'requests',
      description: 'Tracks the number of API calls made.',
    });
    console.log('Meter created:', meter);
  } catch (error) {
    console.error('Error creating meter:', error.message);
  }
}

createMeter();

Example Response

{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks the number of API calls made.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}

Retrieve a Meter#

Retrieves the details of an existing meter. You can retrieve a meter by its unique ID or its event_name.

Parameters

Attribute	Type	Description
id	string	Required. The ID or event_name of the meter to retrieve.

Returns

Returns the Meter object if found.

import payment from '@blocklet/payment-js';

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.message);
  }
}

retrieveMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');

Example Response

{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks the number of API calls made.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}

Update a Meter#

Updates an existing meter by setting the values of the parameters passed.

Parameters

Attribute	Type	Description
id	string	Required. The ID of the meter to update.
name	string	Optional. A new display name for the meter.
description	string	Optional. An updated description for the meter.
status	string	Optional. The new status. Can be active or inactive.
unit	string	Optional. A new unit of measurement for the usage.
metadata	object	Optional. A set of key-value pairs to update on the meter.

Returns

Returns the updated Meter object.

import payment from '@blocklet/payment-js';

async function updateMeter(meterId) {
  try {
    const meter = await payment.meters.update(meterId, {
      name: 'API Calls (V2)',
      description: 'Tracks V2 API calls.',
    });
    console.log('Meter updated:', meter);
  } catch (error) {
    console.error('Error updating meter:', error.message);
  }
}

updateMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');

Example Response

{
  "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
  "name": "API Calls (V2)",
  "event_name": "api.calls.v1",
  "aggregation_method": "sum",
  "unit": "requests",
  "status": "active",
  "livemode": false,
  "currency_id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
  "description": "Tracks V2 API calls.",
  "metadata": {},
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:01:00.000Z",
  "paymentCurrency": {
    "id": "pc_1J7kL2jQ6F9o3vXbY9t8rGcF",
    "name": "API Calls Credit",
    "symbol": "ACC",
    "decimal": 0,
    "type": "credit"
  }
}

List all Meters#

Returns a paginated list of your meters. You can filter the list based on various criteria.

Parameters

Attribute	Type	Description
page	number	Optional. The page number for pagination, starting at 1. Defaults to 1.
pageSize	number	Optional. The number of items to return per page. Defaults to 20.
event_name	string	Optional. Filter meters by a specific event name.
livemode	boolean	Optional. Filter meters by their live mode status.
q	string	Optional. A search query string that filters results based on matching name or description.

Returns

Returns a paginated object containing a list of Meter objects.

Attribute	Type	Description
count	number	The total number of meters matching the query.
list	array	An array of Meter objects for the current page.
paging	object	An object containing pagination information (page, pageSize).

import payment from '@blocklet/payment-js';

async function listMeters() {
  try {
    const result = await payment.meters.list({
      pageSize: 5,
      livemode: false,
    });
    console.log(`Found ${result.count} meters.`);
    console.log('Meters on this page:', result.list);
  } catch (error) {
    console.error('Error listing meters:', error.message);
  }
}

listMeters();

Example Response

{
  "count": 20,
  "list": [
    {
      "id": "mtr_1J7kL2jQ6F9o3vXbY9t8rGcE",
      "name": "API Calls",
      "event_name": "api.calls.v1",
      "status": "active",
      "livemode": false
    },
    {
      "id": "mtr_2K8mN3kR7G0p4wYcZ0u9sHdF",
      "name": "Data Storage",
      "event_name": "data.storage.gb",
      "status": "active",
      "livemode": false
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

Activate a Meter#

Activates an inactive meter. Once activated, the meter will start accepting usage events.

Parameters

Attribute	Type	Description
id	string	Required. The ID of the meter to activate.

Returns

Returns the activated Meter object.

import payment from '@blocklet/payment-js';

async function activateMeter(meterId) {
  try {
    const meter = await payment.meters.activate(meterId);
    console.log(`Meter ${meter.id} is now ${meter.status}.`);
  } catch (error) {
    console.error('Error activating meter:', error.message);
  }
}

activateMeter('mtr_some_inactive_meter_id');

Deactivate a Meter#

Deactivates a meter. The meter will stop accepting new usage events until it is reactivated.

Parameters

Attribute	Type	Description
id	string	Required. The ID of the meter to deactivate.

Returns

Returns the deactivated Meter object.

import payment from '@blocklet/payment-js';

async function deactivateMeter(meterId) {
  try {
    const meter = await payment.meters.deactivate(meterId);
    console.log(`Meter ${meter.id} is now ${meter.status}.`);
  } catch (error) {
    console.error('Error deactivating meter:', error.message);
  }
}

deactivateMeter('mtr_1J7kL2jQ6F9o3vXbY9t8rGcE');

After creating and configuring your meters, the next step is to report usage. See the Meter Events documentation to learn how.