Usage Events
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. 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 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
{
"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" // configured as `source_reference_field`
}
}
]
}
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 used both by the billing portal and later profitability analysis so you can view both revenue and costs for a particular 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
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.