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 Event API or Batch Ingest Usage Events API 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 payload containing arbitrary key-value pairs describing the properties of the event.

Void a usage event

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