Meters

A Meter defines how to aggregate usage events over a billing period to determine how much a customer should be billed.

Endpoints

POST /api/v1/meters/create
GET /api/v1/meters/{id}
POST /api/v1/meters/{id}/update
POST /api/v1/meters/{id}/archive
POST /api/v1/meters/{id}/restore
GET /api/v1/meters
GET /api/v1/meters/{id}/summaries

Create a meter

POST /api/v1/meters/create

Copy for LLMView as Markdown

Create a new Meter object.

Request body

aggregation_methodrequiredstring

Type of aggregation to perform, based on each event's properties value. One of

COUNT: count the number of events.
LAST: the value of the last event.
MAX: maximum of all event values.
SUM: sum up the value of each event.
UNIQUE: count the number of unique events.

aggregation_propertystring

The name of the property within the event to aggregate. Events will be ignored during aggregation if they are missing this property or if its value is invalid.

descriptionstring

Meter description. Used for internal classification and identification.

event_namerequiredstring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

namerequiredstring

Meter name.

request_idrequiredstring

Unique request ID specified by the merchant.

Response body - 201 Created

aggregation_methodstring

Type of aggregation to perform, based on each event's properties value. One of

COUNT: count the number of events.
LAST: the value of the last event.
MAX: maximum of all event values.
SUM: sum up the value of each event.
UNIQUE: count the number of unique events.

aggregation_propertystring

The name of the property within the event to aggregate. Events will be ignored during aggregation if they are missing this property or if its value is invalid.

archivedboolean

false if the Meter is available to be linked to new prices, true otherwise.

created_atstring

Time when this meter was created.

descriptionstring

Meter description. Used for internal classification and identification.

event_namestring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

idstring

ID of the Meter object.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

namestring

Meter name.

updated_atstring

Time when this meter was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/meters/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/meters/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "aggregation_method": "SUM",
>  "aggregation_property": "quantity",
>  "description": "Tracks API requests made by customers",
>  "event_name": "api_call",
>  "metadata": {
>    "foo": "bar"
>  },
>  "name": "API Requests",
>  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9"
>}'

Response (201 Created)

1{
2  "aggregation_method": "SUM",
3  "aggregation_property": "quantity",
4  "archived": false,
5  "created_at": "2022-01-01T10:15:30+0000",
6  "description": "Tracks API requests made by customers",
7  "event_name": "api_call",
8  "id": "mtr_1234567890abcdef",
9  "metadata": {
10    "foo": "bar"
11  },
12  "name": "API Requests",
13  "updated_at": "2022-01-01T10:15:30+0000"
14}

Was this section helpful?

Retrieve a meter

GET /api/v1/meters/{id}

Copy for LLMView as Markdown

Retrieves the details of a Meter.

Parameters

idrequiredstring

ID of the Meter object.

Response body - 200 OK

aggregation_methodstring

Type of aggregation to perform, based on each event's properties value. One of

COUNT: count the number of events.
LAST: the value of the last event.
MAX: maximum of all event values.
SUM: sum up the value of each event.
UNIQUE: count the number of unique events.

aggregation_propertystring

The name of the property within the event to aggregate. Events will be ignored during aggregation if they are missing this property or if its value is invalid.

archivedboolean

false if the Meter is available to be linked to new prices, true otherwise.

created_atstring

Time when this meter was created.

descriptionstring

Meter description. Used for internal classification and identification.

event_namestring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

idstring

ID of the Meter object.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

namestring

Meter name.

updated_atstring

Time when this meter was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/meters/{id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/meters/meter_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "aggregation_method": "SUM",
3  "aggregation_property": "quantity",
4  "archived": false,
5  "created_at": "2022-01-01T10:15:30+0000",
6  "description": "Tracks API requests made by customers",
7  "event_name": "api_call",
8  "id": "mtr_1234567890abcdef",
9  "metadata": {
10    "foo": "bar"
11  },
12  "name": "API Requests",
13  "updated_at": "2022-01-01T10:15:30+0000"
14}

Was this section helpful?

Update a meter

POST /api/v1/meters/{id}/update

Copy for LLMView as Markdown

Update a meter.

Parameters

idrequiredstring

ID of the Meter object.

Request body

descriptionstring

Meter description. Used for internal classification and identification.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

namestring

Meter name.

Response body - 200 OK

aggregation_methodstring

Type of aggregation to perform, based on each event's properties value. One of

COUNT: count the number of events.
LAST: the value of the last event.
MAX: maximum of all event values.
SUM: sum up the value of each event.
UNIQUE: count the number of unique events.

aggregation_propertystring

The name of the property within the event to aggregate. Events will be ignored during aggregation if they are missing this property or if its value is invalid.

archivedboolean

false if the Meter is available to be linked to new prices, true otherwise.

created_atstring

Time when this meter was created.

descriptionstring

Meter description. Used for internal classification and identification.

event_namestring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

idstring

ID of the Meter object.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

namestring

Meter name.

updated_atstring

Time when this meter was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/meters/{id}/update

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/meters/meter_id/update' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "description": "Updated description for tracking API requests made by customers",
>  "metadata": {
>    "foo": "bar"
>  },
>  "name": "Updated API Requests"
>}'

Response (200 OK)

1{
2  "aggregation_method": "SUM",
3  "aggregation_property": "quantity",
4  "archived": false,
5  "created_at": "2022-01-01T10:15:30+0000",
6  "description": "Tracks API requests made by customers",
7  "event_name": "api_call",
8  "id": "mtr_1234567890abcdef",
9  "metadata": {
10    "foo": "bar"
11  },
12  "name": "API Requests",
13  "updated_at": "2022-01-01T10:15:30+0000"
14}

Was this section helpful?

Archive a meter

POST /api/v1/meters/{id}/archive

Copy for LLMView as Markdown

Archive a Meter. The meter will no longer be available to be linked to new Prices. It can be archived only when there is no linked active price.

Parameters

idrequiredstring

ID of the Meter object.

Response body - 200 OK

aggregation_methodstring

Type of aggregation to perform, based on each event's properties value. One of

COUNT: count the number of events.
LAST: the value of the last event.
MAX: maximum of all event values.
SUM: sum up the value of each event.
UNIQUE: count the number of unique events.

aggregation_propertystring

The name of the property within the event to aggregate. Events will be ignored during aggregation if they are missing this property or if its value is invalid.

archivedboolean

false if the Meter is available to be linked to new prices, true otherwise.

created_atstring

Time when this meter was created.

descriptionstring

Meter description. Used for internal classification and identification.

event_namestring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

idstring

ID of the Meter object.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

namestring

Meter name.

updated_atstring

Time when this meter was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/meters/{id}/archive

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/meters/meter_id/archive' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "aggregation_method": "SUM",
3  "aggregation_property": "quantity",
4  "archived": false,
5  "created_at": "2022-01-01T10:15:30+0000",
6  "description": "Tracks API requests made by customers",
7  "event_name": "api_call",
8  "id": "mtr_1234567890abcdef",
9  "metadata": {
10    "foo": "bar"
11  },
12  "name": "API Requests",
13  "updated_at": "2022-01-01T10:15:30+0000"
14}

Was this section helpful?

Restore a meter

POST /api/v1/meters/{id}/restore

Copy for LLMView as Markdown

Restore a Meter. The meter will be available to be linked to new Prices.

Parameters

idrequiredstring

ID of the Meter object.

Response body - 200 OK

aggregation_methodstring

Type of aggregation to perform, based on each event's properties value. One of

COUNT: count the number of events.
LAST: the value of the last event.
MAX: maximum of all event values.
SUM: sum up the value of each event.
UNIQUE: count the number of unique events.

aggregation_propertystring

The name of the property within the event to aggregate. Events will be ignored during aggregation if they are missing this property or if its value is invalid.

archivedboolean

false if the Meter is available to be linked to new prices, true otherwise.

created_atstring

Time when this meter was created.

descriptionstring

Meter description. Used for internal classification and identification.

event_namestring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

idstring

ID of the Meter object.

metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

namestring

Meter name.

updated_atstring

Time when this meter was last updated.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

POST /api/v1/meters/{id}/restore

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/meters/meter_id/restore' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "aggregation_method": "SUM",
3  "aggregation_property": "quantity",
4  "archived": false,
5  "created_at": "2022-01-01T10:15:30+0000",
6  "description": "Tracks API requests made by customers",
7  "event_name": "api_call",
8  "id": "mtr_1234567890abcdef",
9  "metadata": {
10    "foo": "bar"
11  },
12  "name": "API Requests",
13  "updated_at": "2022-01-01T10:15:30+0000"
14}

Was this section helpful?

Get list of meters

GET /api/v1/meters

Copy for LLMView as Markdown

Retrieves a list of Meters based on the query parameters.

Parameters

archivedboolean

The meter's archived status, either true or false.

event_namestring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

aggregation_methodstring

Type of aggregation to perform.

aggregation_propertystring

Property within the event to aggregate.

from_created_atstring

The start time of created_at in ISO8601 format (inclusive).

to_created_atstring

The end time of created_at in ISO8601 format (exclusive).

pagestring

A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.

page_sizeinteger

Number of results per page. Defaults to 20.

Response body - 200 OK

itemsarray

Paged results.

items.aggregation_methodstring

Type of aggregation to perform, based on each event's properties value. One of

COUNT: count the number of events.
LAST: the value of the last event.
MAX: maximum of all event values.
SUM: sum up the value of each event.
UNIQUE: count the number of unique events.

items.aggregation_propertystring

The name of the property within the event to aggregate. Events will be ignored during aggregation if they are missing this property or if its value is invalid.

items.archivedboolean

false if the Meter is available to be linked to new prices, true otherwise.

items.created_atstring

Time when this meter was created.

items.descriptionstring

Meter description. Used for internal classification and identification.

items.event_namestring

The name of the Usage Event to record for. Corresponds with the event_name field on Usage Events.

items.idstring

ID of the Meter object.

items.metadataobject

A set of key-value pairs that you can attach to this object for storing additional information.

items.namestring

Meter name.

items.updated_atstring

Time when this meter was last updated.

page_afterstring

The page cursor used for searching after page.

page_beforestring

The page cursor used for search before page.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/meters

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/meters' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "items": [
3    {
4      "aggregation_method": "SUM",
5      "aggregation_property": "quantity",
6      "archived": false,
7      "created_at": "2022-01-01T10:15:30+0000",
8      "description": "Tracks API requests made by customers",
9      "event_name": "api_call",
10      "id": "mtr_1234567890abcdef",
11      "metadata": {
12        "foo": "bar"
13      },
14      "name": "API Requests",
15      "updated_at": "2022-01-01T10:15:30+0000"
16    }
17  ],
18  "page_after": "<string>",
19  "page_before": "<string>"
20}

Was this section helpful?

Get summaries of a meter

GET /api/v1/meters/{id}/summaries

Copy for LLMView as Markdown

Calculates the result of a Meter for a customer for a given time period.

Parameters

idrequiredstring

ID of the Meter object.

billing_customer_idrequiredstring

ID of the Billing Customer object.

from_happened_atrequiredstring

The start date of Usage Events' happened_at in ISO8601 format (inclusive).

to_happened_atrequiredstring

The end date of Usage Events' happened_at in ISO8601 format (exclusive).

grouped_bystring

The time window to group the usage summary by. If not specified, a single summary for the entire time range is returned. When specified, the response will contain a list of summaries, one for each time window in the range. Possible values are HOUR or DAY. For HOUR grouping, from_happened_at and to_happened_at must align with hour boundaries (e.g., 2025-03-15T14:00:00+0000). For DAY grouping, from_happened_at and to_happened_at must align with UTC day boundaries (e.g., 2025-03-15T00:00:00+0000). If not specified, from_happened_at and to_happened_at must align with minute boundaries e.g., 2025-03-15T14:01:00+0000). The duration must not exceed one year.

pagestring

page_sizeinteger

Number of summaries per page. Defaults to 20.

Response body - 200 OK

itemsarray

Paged results.

items.billing_customer_idstring

ID of the Billing Customer object.

items.event_countinteger

The number of usage events that contributed to the value.

items.from_happened_atstring

Start time of the summary period (inclusive).

items.meter_idstring

ID of the Meter object.

items.to_happened_atstring

End time of the summary period (exclusive).

items.valuenumber

The aggregated value based on the meter's aggregation type.

page_afterstring

The page cursor used for searching after page.

page_beforestring

The page cursor used for search before page.

Errors

Error status	Description
400	Bad Request. Possible error codes: `validation_error`
401	Unauthorized. Possible error codes: `unauthorized`
404	Not Found. Possible error codes: `resource_not_found`
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/meters/{id}/summaries

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/meters/meter_id/summaries' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "items": [
3    {
4      "billing_customer_id": "bcus_1234567890abcdef",
5      "event_count": 100,
6      "from_happened_at": "2022-01-01T00:00:00+0000",
7      "meter_id": "mtr_1234567890abcdef",
8      "to_happened_at": "2022-01-02T00:00:00+0000",
9      "value": 150.75
10    }
11  ],
12  "page_after": "<string>",
13  "page_before": "<string>"
14}

Was this section helpful?