Usage Events are the mechanism by which Merchants report their Customers’ consumption of Billable Metrics to Sulu. Sending Usage Events is the final step in the core loop, triggering real-time billing and payment deductions from the Consumer’s Wallet.

​
Role in Billing and Payments

Whenever a Customer interacts with your Product in a way that consumes a Billable Metric defined in their active Subscription’s Plan, you should report this consumption by sending a Usage Event to Sulu.

Upon receiving a valid Usage Event, Sulu does the following:

  1. Identifies the Customer and their active Subscription.
  2. Looks up the Plan and the Price associated with the billableMetricId(s) reported in the event.
  3. Calculates the cost based on the reported quantity and the applicable Price (considering the pricing model - standard, dynamic, volume).
  4. Instantly deducts the calculated cost from the Consumer Organization’s Wallet.
  5. Instantly credits the calculated cost (minus any applicable fees) to the Merchant Organization’s Wallet.
  6. Records the transaction and updates analytics.

This real-time processing is core to Sulu’s PAYG capabilities.

​
Usage Event Properties

A Usage Event object contains several key pieces of information. Here are some of the most important ones:

​
id
UsageEventId

The unique identifier automatically assigned to the event by Sulu upon successful ingestion.

​
idempotencyKey
string
required

A unique key provided by the Merchant when creating the event. Sulu uses this key to deduplicate events. If you send the same event (with the same idempotencyKey) multiple times within a reasonable window, it will only be processed once, preventing accidental double-billing. It’s crucial to generate a unique key for each distinct usage occurrence.

​
customerId
CustomerId
required

The ID of the Customer resource representing the relationship between the Merchant and the Consumer who consumed the resource.

​
merchantId
OrganizationId
required

The ID of the Merchant Organization reporting the usage.

​
timestamp
date-time
required

The timestamp (in ISO 8601 format) indicating when the usage actually occurred, as reported by the Merchant. This should be accurate and fall within the Customer’s current billing period for their Subscription.

​
properties
array[object]
required

An array detailing the specific Billable Metrics consumed and their quantities in this event. See structure below.

​
billing
object

An object added by Sulu after the event has been successfully processed and billed. It contains details like the calculated price (in smallest currency unit) and the ID of the internal billing transaction.

​
metadata
object

Optional key-value pairs provided by the Merchant for storing additional context or internal references related to the event.

​
Ingestion

Usage events are sent to Sulu via its REST API.

​
Required Fields at Ingestion

When sending a request to create a usage event, you must include:

  • idempotencyKey
  • customerId
  • merchantId (usually inferred from authentication, but required in the body per spec)
  • timestamp
  • properties (detailing the usage)

​
The properties Array

This array is the core of the usage report. Each object within the array represents the consumption of one Billable Metric.

​
properties
array[object]
​
billableMetricId
BillableMetricId
required

The ID of the Billable Metric that was consumed.

​
quantity
number
required

The amount of the Billable Metric’s unit that was consumed in this event (e.g., 1 for one API call, 1024 for 1024 tokens).

​
price
string (decimal)

Required only if the Billable Metric uses the dynamic pricing model. This field specifies the total price (not per unit) to charge for the consumed quantity in this specific event, provided as a decimal string (e.g., “0.05”). This price must fall within the minPrice and maxPrice defined in the Price object on the Plan.

Example properties array:

[
  {
    "billableMetricId": "bm_api_calls_456",
    "quantity": 1
  },
  {
    "billableMetricId": "bm_compute_seconds_789",
    "quantity": 15.5,
    "price": "0.0031" // Required for dynamic pricing
  }
]

​
Timing and Idempotency

  • Reporting Window: Ensure the timestamp you report falls within the current billing period of the customer’s active Subscription. Events reported outside this window may be rejected.
  • Idempotency: Always generate and send a unique idempotencyKey for each distinct usage event you intend to bill for. Retrying a failed request with the same idempotencyKey is safe.

Reporting Usage Events accurately and promptly is key to leveraging Sulu’s real-time billing capabilities.