Report Usage Event
Reports one usage event (value, occurred_at) for an active subscription against a meter, idempotent on event_id.
403 PRODUCT_NOT_ENABLED.X-Idempotency-Key header. Yuno resolves the meter from event_name, validates the event synchronously and stores it against the subscription_id. ACTIVE, TRIALING and PAST_DUE subscriptions accept usage — PAUSED, CANCELED and COMPLETED are rejected with 400 SUBSCRIPTION_NOT_ACTIVE and nothing is counted. Usage is aggregated per subscription and billing cycle according to the meter’s aggregation, and any usage beyond the included credits is billed on the subscription’s renewal charge.
event_id is your idempotency keyGenerate a unique event_id for every event (a UUID or your own event/request id) and reuse it on retries. A replay returns the same response as the first call — including the original value, even if the retry carried a different one (the retry’s value is discarded) — and the usage is never counted twice. event_id is unique per account and required: a request without it is rejected with 400. This is the mechanism that protects billing; X-Idempotency-Key is accepted (optional, as on the rest of the Yuno API) but is not required and is not what dedupes usage.occurred_at defaults to the time Yuno receives the event (returned as received_at). You can backdate up to 35 days; older values are rejected with 400. Which billing cycle an event lands in is decided by occurred_at, not by when it was received.event_name (or an archived meter) is a 400 METER_NOT_FOUND; an unknown subscription_id is a 400 SUBSCRIPTION_NOT_FOUND. The event carries no country or account_id — both are resolved from the subscription.Authorizations
Headers
The account_id found in your Yuno Dashboard (UUID). Required — omitting it returns 400 BAD_REQUEST ("Invalid x-account-code header.").
Unique identifier used in HTTP headers to ensure that a request is processed only once, even if it is retried due to network issues or timeouts. Optional, as on the rest of the Yuno API.
Body
Your unique identifier for this event — the idempotency key. Unique per account. Re-sending the same event_id returns the same response (including the original value) and never counts the usage twice, regardless of retries.
The event_name of the meter this event belongs to. Resolves the meter within your account; an unknown or INACTIVE meter is rejected with 400 METER_NOT_FOUND.
The unique identifier of the subscription the usage is attributed to (MAX 64; MIN 36). Must exist in your account (400 SUBSCRIPTION_NOT_FOUND) and be ACTIVE, TRIALING or PAST_DUE (400 SUBSCRIPTION_NOT_ACTIVE). Usage is metered per subscription and billed on that subscription's renewal.
The quantity to record for this event. Required for SUM, LAST and MAX meters. Must NOT be sent for a COUNT meter — an explicit value is rejected with 400 BAD_REQUEST ("The value must not be provided for a COUNT meter."); each COUNT event is recorded as 1.
When the usage happened (ISO 8601 with offset). Defaults to the time the event is received. Backdating is accepted up to 35 days in the past; older values are rejected with 400 INVALID_PARAMETERS. occurred_at decides which billing cycle the event lands in.
Optional key-value pairs stored with the event (MAX 48 entries; value MAX 512).
Optional guard. When sent it must match the meter resolved from event_name, otherwise the request is rejected with 400 BAD_REQUEST ("The meter_id does not match the meter resolved for event_name '<event_name>'.").