Metering & data
A Usage Event Schema That Survives Your First Pricing Change
By the Orvlin team · · 2 min read
Usage event schema design: what to decide
The first schema often works for the first plan. Trouble starts when sales adds regional rates or a product adds another model. If old events cannot identify those dimensions, historical usage cannot be rated with confidence.
Separate identity from price. Record what happened rather than the dollar amount you hope to charge. Keep an explicit schema version so consumers know whether a quantity represents individual requests or a batch. Reject ambiguous units at ingestion.
How this works in practice
An inference event might record account A, model family B, 1,500 input tokens and 300 output tokens. Two distinct quantities preserve different rates. A single field called tokens would lose that distinction and make a future price change harder to explain.
What can go wrong
More fields are not automatically better. Copying request bodies or personal data into billing records increases exposure without improving invoice calculations. A reference to an operational record is often sufficient.
Questions for your team
- Document required fields and their types.
- Specify UTC timestamps and explicit quantity units.
- Validate zero, negative and unexpectedly large quantities.
- Version the schema before changing field meaning.
Frequently asked questions
- Should events contain the customer’s current price?
- Usually record the activity and let rating apply the appropriate price version. This keeps measurements reusable when contracts or prices change.