Meters | ArcBlock

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.

Create a Meter

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.

Retrieve a Meter

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.

Update a Meter

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`).

List all Meters

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.

Activate a Meter

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.

Deactivate a Meter

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.