Usage events via API

This tutorial will guide you through the steps to create and manage usage events via Billing APIs.

Before you begin

To ensure usage events are successfully ingested, verify that a meter exists with an event_name that matches the one you intend to send. Events sent without a corresponding meter will be rejected.

Create and send usage events

Call the Ingest a Usage EventAPI or Batch Ingest Usage EventsAPI with the following required fields:

• billing_customer_id: The ID of the Customer related to this event.
• event_name: The name of the event. Must match the event_name of a meter to be ingested.
• happened_at: The timestamp of usage. Must be within the past 35 days or up to 5 minutes in the future. Defaults to now.
• merchant_event_id: A unique identifier used for idempotency to prevent double-billing.
• properties: A required object of key-value pairs that describe the event. Put the meter's aggregation value here, for example quantity. Put dimension values here too, using the meter's dimension_keys, for example model and token_type. Ingestion accepts an event when a dimension key is missing or when extra keys are present. See Rate cards via API.

Void a usage event

To invalidate a specific record, call the Void Usage EventAPI using the merchant_event_id. You can void events up to 35 days in the past.