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 Event API or Batch ingest Usage Events API

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

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 Event API.

• 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.