Usage Events are the mechanism by which Merchants report their Customers’ consumption of Billable Metrics to Paygentic. 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 Paygentic. Upon receiving a valid Usage Event, Paygentic 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, percentage).
  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 Paygentic’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 Paygentic upon successful ingestion.
​
idempotencyKey
string
required
A unique key provided by the Merchant when creating the event. Paygentic 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 Paygentic 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 Paygentic via its REST API.
  • Single Event: Use the Create Usage Event endpoint (POST /usage).
  • Multiple Events: For efficiency, you can send multiple events in one request using the Batch Create Usage Events endpoint (POST /usage/batch).
  • Edge Optimization: For improved performance, use edge endpoints like https://edge-api.paygentic.com/v0/usage or regional endpoints for 30-70% latency reduction.

​
Entitlement-Based Usage

Usage events can reference Entitlements to consume pre-authorized funds, providing guaranteed payment: 
{
  "idempotencyKey": "unique-key-123",
  "entitlementId": "ent_xyz789",
  "customerId": "cus_def456",
  "merchantId": "org_abc123",
  "timestamp": "2024-01-15T09:45:00Z",
  "properties": [
    {
      "billableMetricId": "bmt_tokens",
      "quantity": 750
    }
  ]
}

​
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 for dynamic and percentage pricing models.
  • For dynamic pricing: Specifies the total price (not per unit) to charge for the consumed quantity in this specific event. This price must fall within the minPrice and maxPrice defined in the Price object.
  • For percentage pricing: Specifies the base amount (e.g., invoice total, transaction amount) on which the percentage is calculated. The actual charge will be baseAmount * percentage, bounded by minCharge and maxCharge.
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
  },
  {
    "billableMetricId": "bm_revenue_share_123",
    "quantity": 1,
    "price": "250.00" // Base amount for percentage pricing (e.g., $250 invoice)
  }
]

​
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 Paygentic’s real-time billing capabilities.