# Send Usage Events

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

Submit actual usage events such as API calls, AI workloads, or product outcomes. Billable events are processed in real time and immediately debit the customer’s wallet.

Each event must have a unique ID to ensure idempotency, preventing double billing if the same event is submitted multiple times.

<!-- -->

Customers are billed based on their [product subscriptions](https://docs.credyt.ai/quickstart/create-a-customer.md#product-subscriptions). Usage events are matched against the corresponding products' [usage calculation configuration](https://docs.credyt.ai/quickstart/create-a-product.md). For example, if a product has a `video_promoted` event type configured, sending a usage event of that type will calculate and debit a usage fee from the customer's wallet.

note

The response from the [Usage API](https://docs.credyt.ai/api/events-send-usage.md) does not include the updated wallet balance. To check the current balance after usage is processed, you can use the [Wallet API](https://docs.credyt.ai/api/customer-wallet-ops-get-customer-wallet.md).

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

## Using external identifiers[​](#using-external-identifiers "Direct link to Using external identifiers")

Alternatively you can specify the customer's external identifier in the `customer_external_id` field. This may be preferable if sending usage is in your application "hot path" and you want to avoid unnecessary lookups:

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

* REST API
* TypeScript SDK
* Python SDK

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

```json
{
  "customer_external_id": "<your customer ID or reference>",
  "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({
  customerExternalId: "<your customer ID or reference>",
  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#L117)

```python
response = client.events.send_usage(
    body={
    "customer_external_id": "<your customer ID or reference>",
    "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_by_external_id.py#L20)