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 processes it based on whether an entitlement is provided:

​
Standard Processing (Without Entitlement)

  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.

​
Entitlement-Based Processing

When an entitlementId is included:
  1. Validates the entitlement exists and has remaining capacity.
  2. Calculates the cost using the same pricing logic.
  3. Deducts from the pre-reserved entitlement funds (not the wallet).
  4. Credits the merchant’s wallet immediately.
  5. Updates the entitlement’s remaining balance.
This dual processing model enables both flexible pay-as-you-go billing and guaranteed payment collection through entitlements.

​
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.
​
entitlementId
string
Optional ID of a pre-authorized entitlement (format: com_*). When provided, the usage is deducted from the entitlement’s reserved funds rather than directly from the wallet, guaranteeing payment availability.
​
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

Entitlements provide pre-authorized payment reservations that guarantee funds availability before usage occurs. When you include an entitlementId in your usage event, Paygentic deducts from the reserved funds rather than directly from the wallet, ensuring payment is guaranteed. 
{
  "idempotencyKey": "unique-key-123",
  "entitlementId": "com_xyz789",  // Optional: Links to pre-authorized funds
  "customerId": "cus_def456",
  "merchantId": "org_abc123",
  "timestamp": "2024-01-15T09:45:00Z",
  "properties": [
    {
      "billableMetricId": "bmt_tokens",
      "quantity": 750
    }
  ]
}
Key benefits of entitlement-based usage:
  • Guaranteed payment: Funds are reserved upfront, eliminating payment failures
  • Lower latency: Regional entitlements enable ultra-fast processing via edge instances
  • Better control: Set usage limits with maxUses parameter for multi-use entitlements
For high-frequency or latency-sensitive applications, consider using regional entitlements via edge instances for optimal performance.

​
Required Fields at Ingestion

When sending a request to create a usage event, you must include:
  • idempotencyKey - Unique key to prevent duplicate processing
  • customerId - ID of the customer generating the usage
  • merchantId - ID of the merchant organization (usually inferred from authentication)
  • timestamp - When the usage occurred (ISO 8601 format)
  • properties - Array detailing the billable metrics consumed
Optional but recommended:
  • entitlementId - ID of a pre-authorized entitlement to deduct from (format: com_*)
  • metadata - Additional context or internal references

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