> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Events

> Report consumption and trigger billing

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.

<Warning>
  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](/platform/metering/meter-events). For a comparison of the two billing models,
  see [Billing Versions](/platform/billing/billing-versions).
</Warning>

## 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:

```json theme={null}
{
  "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

<Note>
  `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](/platform/pricing/prices).
</Note>

### 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

* [Customer Lifecycle](/platform/billing/customer-lifecycle) - Understand billing flows
* [Entitlements](/platform/billing/entitlements) - Pre-authorize payments
* [Accounts](/platform/payments/accounts) - Manage payment instruments