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.

​
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

​
Standard Pricing

Fixed rate multiplication. Quantity × configured unit price.

​
Dynamic Pricing

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

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

​
Idempotency & 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