Meters
Meters are used to define and track usage for credit-based billing. Each meter corresponds to a specific billable item that you report usage against, identified by a unique event_name. For example, you could create a meter to track API calls, data storage, or compute time.
Once a meter is created, you can report usage events for your customers. To learn more about the overall workflow, see the Credit-Based Billing guide.
The Meter Object#
A Meter object contains all the information about a specific usage metric you want to track.
Attribute | Type | Description |
|---|---|---|
|
| Unique identifier for the meter, prefixed with |
|
| The display name of the meter. |
|
| The unique system name for the event being metered. This is used when reporting usage. |
|
| The method for aggregating usage events. Currently, only |
|
| The unit of measurement for the usage (e.g., 'requests', 'tokens', 'bytes'). |
|
| The ID of the payment currency associated with this meter. |
|
| The current status of the meter. Can be |
|
|
|
|
| An optional description for the meter. |
|
| A set of key-value pairs for storing additional custom information. |
|
| ISO 8601 timestamp indicating when the meter was created. |
|
| ISO 8601 timestamp indicating the last time the meter was updated. |
|
| Expanded. The associated payment currency object, providing details like symbol and decimal places. |
Create a Meter#
Creates a new meter to track a specific type of usage. The event_name must be unique for a given mode (live or test).
Parameters
Parameter | Type | Description |
|---|---|---|
|
| Required. The display name for the meter. Maximum 64 characters. |
|
| Required. A unique name for the event you are tracking (e.g., |
|
| Required. The unit of measure for this meter (e.g., |
|
| The method for aggregating usage. Defaults to |
|
| The ID of an existing currency to associate with this meter. If not provided, a new currency will be created automatically. |
|
| An optional description for the meter. Maximum 255 characters. |
|
| A set of key-value pairs that you can attach to the object. |
Returns
Returns the newly created Meter object.
Example
import payment from '@blocklet/payment-js';
async function createApiCallMeter() {
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 by a user.'
});
console.log('Meter created:', meter);
} catch (error) {
console.error('Error creating meter:', error.message);
}
}
createApiCallMeter();Example Response
{
"id": "mtr_abc123def456",
"name": "API Calls",
"event_name": "api.calls.v1",
"aggregation_method": "sum",
"unit": "requests",
"currency_id": "pcur_xyz789uvw012",
"status": "active",
"livemode": false,
"description": "Tracks the number of API calls made by a user.",
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z",
"paymentCurrency": {
"id": "pcur_xyz789uvw012",
"name": "API Calls",
"symbol": "requests",
"decimal": 0,
"type": "meter"
}
}Retrieve a Meter#
Retrieves the details of an existing meter. You can fetch the meter using either its ID or its unique event_name.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| Required. The unique identifier ( |
Returns
Returns the Meter object if found.
Example
import payment from '@blocklet/payment-js';
async function getMeter(identifier) {
try {
const meter = await payment.meters.retrieve(identifier);
console.log('Meter found:', meter);
} catch (error) {
console.error('Error retrieving meter:', error.message);
}
}
// Retrieve by ID
getMeter('mtr_abc123def456');
// Alternatively, retrieve by event_name
getMeter('api.calls.v1');Update a Meter#
Updates an existing meter by setting the values of the provided parameters.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| Required. The ID of the meter to update. |
|
| The new display name for the meter. |
|
| An updated description for the meter. |
|
| The new unit of measurement for the meter. |
|
| The new status for the meter. Can be |
|
| A new set of key-value pairs. This will replace any existing metadata. |
Returns
Returns the updated Meter object.
Example
import payment from '@blocklet/payment-js';
async function updateMeterDescription(meterId) {
try {
const meter = await payment.meters.update(meterId, {
description: 'Tracks all V1 API calls, including deprecated endpoints.'
});
console.log('Meter updated:', meter.description);
} catch (error) {
console.error('Error updating meter:', error.message);
}
}
updateMeterDescription('mtr_abc123def456');List all Meters#
Returns a paginated list of your meters. The meters are returned sorted by creation date, with the most recently created meters appearing first.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| The page number to retrieve. Defaults to |
|
| The number of meters to return per page. Defaults to |
|
| Filters the list to meters with this specific |
|
| Filters the list based on the mode (live or test). |
|
| A query string to search for meters by name or description. |
Returns
Returns a paginated object containing a list of Meter objects, the total count, and paging information.
Example
import payment from '@blocklet/payment-js';
async function listMeters() {
try {
const response = await payment.meters.list({ pageSize: 5 });
console.log(`Showing ${response.list.length} of ${response.count} total meters.`);
response.list.forEach(meter => {
console.log(`- ${meter.name} (ID: ${meter.id})`);
});
} catch (error) {
console.error('Error listing meters:', error.message);
}
}
listMeters();Example Response
{
"count": 1,
"list": [
{
"id": "mtr_abc123def456",
"name": "API Calls",
"event_name": "api.calls.v1",
"aggregation_method": "sum",
"unit": "requests",
"currency_id": "pcur_xyz789uvw012",
"status": "active",
"livemode": false,
"description": "Tracks all V1 API calls, including deprecated endpoints.",
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:05:00.000Z",
"paymentCurrency": {
"id": "pcur_xyz789uvw012",
"name": "API Calls",
"symbol": "requests",
"decimal": 0,
"type": "meter"
}
}
],
"paging": {
"page": 1,
"pageSize": 5
}
}Activate a Meter#
Changes a meter's status to active.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| Required. The ID of the meter to activate. |
Returns
Returns the updated Meter object with a status of active.
Example
import payment from '@blocklet/payment-js';
async function activateMeter(meterId) {
try {
const meter = await payment.meters.activate(meterId);
console.log(`Meter ${meter.id} status is now: ${meter.status}`);
} catch (error) {
console.error('Error activating meter:', error.message);
}
}
activateMeter('mtr_abc123def456');Deactivate a Meter#
Changes a meter's status to inactive. Inactive meters will not accept new usage events.
Parameters
Parameter | Type | Description |
|---|---|---|
|
| Required. The ID of the meter to deactivate. |
Returns
Returns the updated Meter object with a status of inactive.
Example
import payment from '@blocklet/payment-js';
async function deactivateMeter(meterId) {
try {
const meter = await payment.meters.deactivate(meterId);
console.log(`Meter ${meter.id} status is now: ${meter.status}`);
} catch (error) {
console.error('Error deactivating meter:', error.message);
}
}
deactivateMeter('mtr_abc123def456');After managing your meters, the next step is to report usage against them. See the Meter Events documentation to learn how.