Usage Events

A Usage Event represents a customer's usage of a product at a specific timestamp.

Endpoints

POST /api/v1/usage_events/ingest
POST /api/v1/usage_events/batch_ingest
POST /api/v1/usage_events/void

Ingest a usage event

POST /api/v1/usage_events/ingest

Copy for LLMView as Markdown

Ingest a single usage event. The event is validated synchronously, but is processed asynchronously. For higher rate limits, please use the Batch Ingest Usage Events API instead.

Request body

billing_customer_idrequiredstring

ID of the Billing Customer related to this usage event.

event_namerequiredstring

The name of the event. Corresponds with the event_name field on a meter.

happened_atstring

Time when this event happened. Must be within the past 35 days or up to 5 minutes in the future. Defaults to now.

merchant_event_idrequiredstring

A unique identifier for the event. This value must be unique within a rolling 35-day period and is limited to a maximum of 64 characters.

propertiesrequiredobject

The payload of events, which contains arbitrary key-value pairs storing properties of the event.

Response body - 201 Created

billing_customer_idstring

ID of the Billing Customer related to this usage event.

event_namestring

The name of the event. Corresponds with the event_name field on a meter.

happened_atstring

Time when this event happened.

ingested_atstring

Time when this usage event was ingested.

merchant_event_idstring

Unique identifier of this event in the merchant's system. Maximum length is 64.

propertiesobject

The payload of events, which contains arbitrary key-value pairs storing properties of the event.

voidedboolean

Indicates the status of the event. If true, it means the event has been voided and would not be counted into meter result calculation.

voided_atstring

Time when this usage event was voided.

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/usage_events/ingest

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/usage_events/ingest' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",
>  "event_name": "api_call",
>  "happened_at": "<date-time>",
>  "merchant_event_id": "merchant_event_12345",
>  "properties": {
>    "quantity": "1",
>    "region": "us-east-1",
>    "userId": "userA"
>  }
>}'

Response (201 Created)

1{
2  "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",
3  "event_name": "api_call",
4  "happened_at": "<date-time>",
5  "ingested_at": "<date-time>",
6  "merchant_event_id": "merchant_event_12345",
7  "properties": {
8    "quantity": "1",
9    "region": "us-east-1",
10    "userId": "userA"
11  },
12  "voided": false,
13  "voided_at": "2025-08-03T00:00:00+0000"
14}

Was this section helpful?

Batch ingest usage events

POST /api/v1/usage_events/batch_ingest

Copy for LLMView as Markdown

Ingest new usage events in a batch. The events are validated and processed asynchronously. If errors occur, webhook events will be published. Maximum 10 events per request.

Request body

eventsrequiredarray

List of usage events to ingest. Maximum 10 events per request.

events.billing_customer_idrequiredstring

ID of the Billing Customer related to this usage event.

events.event_namerequiredstring

The name of the event. Corresponds with the event_name field on a meter.

events.happened_atstring

Time when this event happened. Must be within the past 35 days or up to 5 minutes in the future. Defaults to now.

events.merchant_event_idrequiredstring

A unique identifier for the event. This value must be unique within a rolling 35-day period and is limited to a maximum of 64 characters.

events.propertiesrequiredobject

The payload of events, which contains arbitrary key-value pairs storing properties of the event.

Response body - 202 Accepted

Accepted

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/usage_events/batch_ingest

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/usage_events/batch_ingest' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "events": [
>    {
>      "billing_customer_id": "bcus_hkpd7fedfgb004apkvs",
>      "event_name": "api_call",
>      "merchant_event_id": "merchant_event_12345",
>      "properties": {
>        "quantity": "1",
>        "region": "us-east-1",
>        "userId": "userA"
>      }
>    }
>  ]
>}'

Was this section helpful?

Void a usage event

POST /api/v1/usage_events/void

Copy for LLMView as Markdown

Void a previous usage event ingested within 35 days.

Request body

merchant_event_idrequiredstring

Unique identifier of a previous event.

Response body - 202 Accepted

Accepted

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/usage_events/void

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/usage_events/void' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "merchant_event_id": "merchant_event_12345"
>}'

Was this section helpful?