The usage event object

Fields

Field	Type	Always present	What it means
id	string	Yes
tenant_id	string	No
customer_id	string	Yes
meter_id	string	Yes
quantity	string	Yes	Exact quantity as a decimal string (e.g. “1.5”).
dimensions	object	No	The dimension values sent with the event. Absent when none were sent.
idempotency_key	string	No
timestamp	string (date-time)	Yes
origin	enum	No	How the event arrived. backfill means POST /v1/usage-events/backfill. One of: api, backfill.
provider_cost_cents	string	No	What serving this event cost you at your provider, in US cents as a decimal string (e.g. “0.45”), set when the event arrived: from your provider cost rates, or the cost the sender reported (see provider_cost_source). Absent when the cost is unknown or the event has no costed dimensions.
provider_cost_source	enum	No	Where provider_cost_cents came from: table (your provider cost rates), observed (the cost the sender reported), or not_applicable (the meter has no costed dimensions). Absent when the cost is unknown. One of: table, not_applicable, observed.
billing_status	enum	No	What Hardcount found when the event arrived. It checked the event against the customer’s subscriptions, the plans and prices in force, and the invoices already built at that moment. Sent only on the answer that wrote the event; the event is stored all the same. A status that is present was true at that moment: - after_close: the event’s time is already invoiced. A spend-threshold invoice counts only once it is paid. Bill the event with a one-off invoice if it should be charged. - not_on_plan: a billing period not invoiced yet holds the event’s time, but its plan has no price for this meter. - outside_subscription: no active or trialing subscription of the customer bills the event’s time. For example, it has none, or the time is before one starts, in a free trial, or after one ends or its scheduled cancel. - no_price: the plan that bills the event’s time prices this meter, but no price of that plan takes the event’s dimensions. A price takes an event whose dimensions include all of its dimension_match, compared as strings: the number 1 is not the string "1". No billing_status means Hardcount found no reason then. It is not a promise that the event will be billed. Hardcount checks only the customer’s current billing periods: time after a period end whose invoice is not built yet is not checked, nor is time after a trial’s end before Hardcount ends the trial. A later change can change the outcome either way: a subscription created, activated or changed, a trial extended, a scheduled cancel undone, or a price added. The invoice is the final answer. Two cases can make a present status wrong: a price change whose save began before a billing period started and finished after the request read the prices, and a subscription change saved while the request is in flight. Absent on a replay and on a read. One of: after_close, no_price, not_on_plan, outside_subscription.