Usage events

A Usage Event is a record of a specific instance of product consumption. It serves as the raw input for usage-based billing by capturing the "who (customer), what (event name), when (timestamp) and how much (quantity)" of each consumption instance.

By capturing these instances, you can automate the transformation of raw consumption data to billable quantities for invoicing.

Integration

As the primary source of truth for customer activity, your application backend must trigger the creation of usage events by calling the Ingest a Usage EventAPI or Batch ingest Usage EventsAPI

You can choose a reporting strategy that aligns with your system architecture and business needs:

• Real-time: Dispatch usage events immediately as consumption occurs
  • e.g. sending a usage event as soon as a customer generates an AI image
• Pre-aggregated: Aggregate usage locally and send a summary usage event at set intervals
  • e.g. sending a single daily event representing the total GB of data uploaded by a customer

Event properties and dimensions

Every usage event includes a required properties object: arbitrary key-value pairs that describe the consumption instance.

A meter selects one of those keys as its aggregation property — the value it sums, counts, or otherwise aggregates. Every other key is stored with the event.

The smallest event that supports a billable quantity only needs that aggregation property. For example, a meter that sums quantity for events named tokens can invoice from:

1{
2  "event_name": "tokens",
3  "properties": {
4    "quantity": "100"
5  }
6}

Additional keys in properties — for example model, token_type, and mode — describe the same instance in more detail:

1{
2  "event_name": "tokens",
3  "properties": {
4    "quantity": "100",
5    "model": "standard",
6    "token_type": "input",
7    "mode": "standard"
8  }
9}

Multi-dimensional pricing uses those extra keys for billing. When the meter declares selected property names as dimension keys, it groups usage by them: aggregation still uses the meter's method (SUM, COUNT, and so on), but it yields one quantity per distinct combination of dimension values, for example {model: standard, token_type: input, mode: standard}. A Rate Card then assigns a price to each of those combinations.

Undeclared properties remain metadata: they are accepted and stored, but they do not affect aggregation. Dimension keys do not need to be present on every event. Ingestion does not reject an event because a dimension key is missing or because extra keys are present.

If those extra keys are already on the event, you can append them as dimension keys on an existing meter without changing your event payload. Dimension keys affect only that meter's grouping. The same event can still be processed by more than one meter, as described in Deriving multiple metrics from a single event.

Deriving multiple metrics from a single event

A single usage event can be processed by multiple meters simultaneously. This allows you to derive different billable quantities from a single data stream without modifying your backend integration.

For example, a "file upload" event can be COUNTED by one meter to track the number of files and SUMMED by another to track the total storage size.

Void a usage event

Voiding allows you to invalidate a previously sent usage event to ensure billing accuracy. This is necessary if an event was sent in error, such as when it contains an incorrect usage quantity.

To void a usage event, call the Void a Usage EventAPI.

• Impact on invoicing: Once a usage event is voided, it is excluded from all meter aggregations and billing calculations. Voiding an event does not retroactively adjust or update finalised invoices. To fix errors on finalised invoices:
  • If you overcharged: Issue a credit note
  • If you undercharged: Issue a separate one-off invoice
• Best practice: To minimise billing discrepancies, void usage events as soon as an error is detected and before the current billing period ends. You can void events up to 35 days in the past.

Late-arriving events

For subscriptions containing usage-based products, Airwallex provides a one-hour grace period after the billing period ends. This allows the system to capture usage events that occurred during the period but experienced a delay in ingestion.

• During the grace period: Events are ingested and included in the latest invoice.
• After the grace period: Invoice status is FINALIZED. Any events received — even if they occurred during the previous period — will not be included in the invoice and will not trigger retroactive adjustments.

Example:

• Billing period end: 11 Jan, 12:00 AM
• Usage event 1:
  • happened_at = 10 Jan, 11:55 PM
  • ingested_at = 11 Jan 12:10 AM
• Invoice finalised: 11 Jan, 1:00 AM
• Usage event 2:
  • happened_at = 10 Jan, 11:55 PM
  • ingested_at = 11 Jan 1:05 AM
• Result: Usage event 1 is included in the 11 Jan invoice as it was ingested before the invoice was finalised. Usage event 2 will not be reflected in the 11 Jan invoice.