# Usage Events

[API Reference](https://docs.credyt.ai/api/events-send-usage.md)

Usage events represent the activities in your system that you want to bill or (in the future) track costs for. Each event corresponds to a measurable outcome, such as an API call, a chat completion, or a video processed.

Every usage event has a unique identifier that serves as an idempotency key. This ensures safe retries without accidental double billing, even if the same event is submitted multiple times due to network issues or other errors.

When sending usage events you must provide a valid customer identifier. This allows Credyt to match the usage to the correct customer account and apply the appropriate pricing according to their [subscriptions](https://docs.credyt.ai/features/customers.md#subscribe-a-customer-to-a-product). Usage not linked to a valid subscription will be ignored.

Usage events are billed in real time and the customer's balance will be debited as soon as an event is processed. Credyt supports a number of usage-based pricing models:

* **`unit`** – charges per occurrence of the event (e.g., per chat, per verification, per API call).
* **`volume`** – charges based on the volume or quantity consumed, included in the event payload (e.g., tokens, minutes, megabytes).
* **`unit_and_volume`** – combines both approaches

The `event_type` specified in the usage event must match the `event_type` configured in a product price’s usage calculation configuration for it to be charged for. View [Products and Pricing](https://docs.credyt.ai/features/product-catalog.md) guide for more details.

By combining usage events with Credyt’s wallet and rate plan structure, you can build flexible, customer-friendly monetization models, whether you charge in fiat, tokens, or other custom units.

### Example[​](#example "Direct link to Example")

* REST API
* TypeScript SDK
* Python SDK

POST https\://api.credyt.ai/events

```json
{
  "customer_id": "cust_473cr1y0ghbyc3m1yfbwvn3nxx",
  "events": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "event_type": "video_promoted",
      "occurred_at": "2025-10-17T21:21:27.024729Z",
      "subject": "video_5f53d23a4958",
      "description": "Video Promoted",
      "data": {
        "promo_id": "pro_4tbftjwzxja1h71nzas1g0g1xm"
      }
    }
  ]
}

```

```typescript
await client.events.sendUsage({
  customerId: "cust_473cr1y0ghbyc3m1yfbwvn3nxx",
  events: [
    {
      id: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      eventType: "video_promoted",
      occurredAt: "2025-10-17T21:21:27.024729Z",
      subject: "video_5f53d23a4958",
      description: "Video Promoted",
      data: {
        promoId: "pro_4tbftjwzxja1h71nzas1g0g1xm",
      },
    },
  ],
});

```

[View full sample on GitHub](https://github.com/credyt/sdk-ts/blob/main/samples/eventsSendUsageSample.ts#L93)

```python
response = client.events.send_usage(
    body={
    "customer_id": "cust_473cr1y0ghbyc3m1yfbwvn3nxx",
    "events": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "event_type": "video_promoted",
        "occurred_at": "2025-10-17T21:21:27.024729Z",
        "subject": "video_5f53d23a4958",
        "description": "Video Promoted",
        "data": {
          "promo_id": "pro_4tbftjwzxja1h71nzas1g0g1xm",
        },
      },
    ],
  },
)

```

[View full sample on GitHub](https://github.com/credyt/sdk-python/blob/main/samples/events_send_usage_video_promoted.py#L20)

Note how `"promo_id": "pro_4tbftjwzxja1h71nzas1g0g1xm"` has been configured as `source_reference_field`.

## Correlating Usage[​](#correlating-usage "Direct link to Correlating Usage")

We recommend you include the `subject` field in all usage events to correlate the usage to an activity in your system. This is displayed in the Usage history section of the [Billing portal](https://docs.credyt.ai/features/billing-portal.md), and feeds into [Profitability analysis](https://docs.credyt.ai/features/profitability.md) and [Tasks](https://docs.credyt.ai/features/tasks.md) - giving you a full view of both revenue and costs for any given activity.

For finer grained traceability, you can include an additional reference that can be linked to a product price's `source_reference_field`.

## Simulating Usage[​](#simulating-usage "Direct link to Simulating Usage")

Usage events can also be simulated before they affect actual balances. This is useful for validating new product configurations, experimenting with pricing models, or testing new features without impacting live customers. Simulated events calculate fees in the same way as live events but do not modify the wallet balance.