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

# Event Pipeline

> How usage events move from your application into billing and margin reporting

Usage billing starts with an application-owned event. Each logical event should have a stable transaction ID, a customer, a Feature code, and the properties required by that metric.

## 1. Track from your backend

```ts title="Node.js" theme={null}
import { Nozle } from '@nozle-js/node'

const nozle = new Nozle({
  apiKey: process.env.NOZLE_SECRET_KEY!,
  baseUrl: 'https://api.nozle.app',
  eventsUrl: 'https://core.nozle.app',
})

await nozle.track(
  'customer_123',
  'api_calls',
  { model: 'example-model', tokens: 1_500 },
  {
    subscriptionId: 'subscription_123',
    transactionId: 'request_0183f',
    timestamp: '2026-08-04T10:30:00Z',
  },
)
```

```python title="Python" theme={null}
from nozle import Nozle

nozle = Nozle(
    api_key="sk_example",
    base_url="https://api.nozle.app",
    events_url="https://core.nozle.app",
)

nozle.track(
    "customer_123",
    "api_calls",
    metadata={"model": "example-model", "tokens": 1_500},
    subscription_id="subscription_123",
    transaction_id="request_0183f",
    timestamp="2026-08-04T10:30:00Z",
)
```

## 2. Ingest and deduplicate

Nozle accepts the event through the configured Events API. Preserve both the transaction ID and event timestamp when retrying the same logical event. Deployments using the high-volume event store deduplicate on both values.

## 3. Aggregate usage

Metered Features define how properties are aggregated, including count, sum, maximum, and unique count. Property names must match the Feature configuration exactly.

## 4. Invoice and analyze

Aggregated usage becomes invoice charges according to the plan's pricing model. The same event metadata can feed cost models and margin reporting.

## Product-credit events

For actions that must be authorized and deducted from product credits, call `usage.track()` instead of sending a plain event. Nozle records the credit operation and queues the matching billing event in one durable workflow.

## Operational guidance

* Publish from a durable worker for high-volume or business-critical telemetry.
* Reuse the same transaction ID and timestamp on retries.
* Supply `subscriptionId` explicitly when a customer can have multiple active subscriptions.
* Do not expect a plain event to reserve credits or synchronously update an invoice.