Skip to main content
Usage events are the fundamental unit of consumption tracking in Paygentic. Each event represents a discrete consumption of resources that triggers immediate billing calculations and payment processing.
This page describes the usage event model for Legacy Billing (billingVersion: 0), where each event triggers a real-time transaction against the customer’s account. If you are on Standard Billing (billingVersion: 1), send meter events instead — see Meter Events. For a comparison of the two billing models, see Billing Versions.

​
Core mechanics

When a customer consumes a metered resource, you create a usage event that captures:
  • Who consumed it (customer ID)
  • What was consumed (metric ID and quantity)
  • When it occurred (timestamp)
  • How to prevent duplicates (idempotency key)
The billing engine processes each event through a deterministic pipeline: validation → pricing → payment → settlement.

​
Event processing models

​
Direct account processing

Standard flow for real-time billing:
  1. Event arrives with customer and metric identifiers
  2. System resolves active subscription and pricing rules
  3. Cost calculation based on quantity × unit price (or dynamic/percentage models)
  4. Immediate account debit from consumer
  5. Instant credit to merchant (minus platform fees)
  6. Transaction recording and analytics update

​
Entitlement-based processing

Pre-authorized payment flow:
  1. Event includes entitlement ID linking to reserved funds
  2. Same pricing calculation occurs
  3. Deduction from pre-reserved entitlement balance
  4. Merchant credit remains immediate
  5. Entitlement balance decrements
This dual-path architecture enables both flexible pay-per-use and guaranteed payment scenarios.

​
Event structure

Essential fields for every usage event: Identity & Deduplication
  • idempotencyKey - Unique identifier preventing duplicate processing
  • customerId - Links consumption to specific customer relationship
  • merchantId - Identifies the service provider
Consumption Details
  • timestamp - Exact moment of resource consumption (ISO 8601)
  • properties - Array of metric consumption records
Optional Enhancements
  • entitlementId - References pre-authorized payment reservation
  • metadata - Arbitrary key-value pairs for internal tracking

​
Consumption properties

Each element in the properties array represents one metric’s consumption: 
{
  "billableMetricId": "metric_identifier",
  "quantity": 100,
  "price": "dynamic_or_base_amount"  // Required for dynamic/percentage pricing
}
The price field serves different purposes based on the pricing model:
  • Dynamic pricing: Total cost for this specific consumption
  • Percentage pricing: Base amount for percentage calculation
  • Standard pricing: Not required (uses plan’s fixed rate)

​
Pricing model interactions

dynamic and percentage are legacy models. Existing prices that use them keep billing exactly as described below, but new prices can no longer be created with them — use standard instead. For percentage / revenue share, create a standard price whose unit price is the rate (a unit price of 0.1 charges 10% of the metered value). See Prices.

​
Standard pricing

Fixed rate multiplication. Quantity × configured unit price. For percentage-style charges, set the unit price to the rate and send the base amount as the quantity.

​
Dynamic pricing (legacy)

Runtime price determination. The event carries the actual price within bounds set by the plan. Useful for spot pricing, market rates, or time-based variations.

​
Percentage pricing (legacy)

Transaction-based fees. The event includes the transaction amount; the system calculates the percentage cut with min/max bounds applied.

​
Idempotency and reliability

The idempotency key ensures exactly-once processing semantics:
  • Same key within time window → subsequent attempts ignored
  • Failed requests can be safely retried with identical payload
  • Generate deterministic keys from your internal identifiers
Best practice: Derive keys from your system’s unique identifiers (e.g., hash of transaction ID + metric ID).

​
Timing constraints

Events must align with subscription billing periods:
  • Timestamp within active subscription range
  • Events outside current period may be rejected
  • Historical backfill requires special handling

​
Batch processing

For high-volume scenarios, batch multiple events in a single request:
  • Reduces network overhead
  • Atomic processing (all succeed or all fail)
  • Same validation rules per event
  • Ideal for periodic bulk reporting

​
Regional optimization

Leverage edge infrastructure for reduced latency:
  • Regional endpoints process events locally
  • Entitlements enable ultra-low latency processing
  • Critical for real-time applications

​
Error handling

Common failure scenarios and recovery: Validation Failures
  • Invalid customer/metric IDs → verify references exist
  • Timestamp outside billing period → check subscription status
  • Price outside dynamic bounds → validate against plan limits
Payment Failures
  • Insufficient account balance → requires top-up or entitlement
  • Entitlement exhausted → create new entitlement
  • Network timeouts → retry with same idempotency key

​
Design patterns

​
High-frequency reporting

For systems generating thousands of events per second:
  • Buffer and batch events locally
  • Use entitlements to guarantee payment
  • Leverage regional endpoints
  • Implement exponential backoff for retries

​
Guaranteed delivery

For critical billing accuracy:
  • Local event queue with persistence
  • Idempotency keys derived from queue position
  • Dead letter queue for failed events
  • Periodic reconciliation jobs

​
Cost attribution

For detailed cost tracking:
  • Rich metadata on each event
  • Hierarchical customer IDs for sub-accounts
  • Temporal bucketing for period analysis
  • Tag-based grouping in metadata

​
Next steps