Usage events API
Usage events record consumption for metered subscription items. Floatless stores raw usage events and uses them when rating usage and generating invoices.
Endpoint
| Method | Endpoint | Description |
|---|---|---|
| POST | /usage/events |
Create a metered usage event |
Idempotency
Send an Idempotency-Key header with every usage event. If your system retries after a timeout or network error, reuse the same key for the same event.
Idempotency-Key: 1d7a3870-2f87-4c31-b5df-0b4f59aaaf73
Keys can be up to 255 characters. Use a UUID or another high-entropy event identifier. Do not put personal data or secrets in idempotency keys.
Create a usage event
curl https://api.floatless.com/api/public/v1/usage/events \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 1d7a3870-2f87-4c31-b5df-0b4f59aaaf73" \
-d '{
"subscription_item_id": 789,
"quantity": 42,
"timestamp": "2026-07-07T10:15:00Z"
}'
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
subscription_item_id |
integer | Yes | Metered subscription item ID |
quantity |
number | Yes | Usage quantity for this event, greater than zero |
timestamp |
datetime | No | When usage happened; defaults to receipt time |
idempotency_key |
string | No | Body fallback if the header is not sent |
Response
{
"data": {
"id": "2fbc3997-56cf-4fbf-8f98-40a521abfb6a",
"object": "usage_event",
"subscription_item_id": 789,
"quantity": 42,
"timestamp": "2026-07-07T10:15:00Z",
"idempotency_key": "1d7a3870-2f87-4c31-b5df-0b4f59aaaf73",
"recorded_at": "2026-07-07T10:15:02Z"
}
}
Error cases
| Code | error_code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST |
Missing Idempotency-Key, or the subscription item is not metered |
| 401 | UNAUTHORIZED |
Missing or invalid API key |
| 404 | NOT_FOUND |
Subscription item does not exist in your organization |
| 422 | VALIDATION_ERROR |
quantity is not greater than zero, or the body fails schema validation — details lists each field error |
| 500 | INTERNAL_SERVER_ERROR |
Unexpected server error |
Replay behavior
Replaying a request with the same idempotency key for the same subscription item returns the existing stored event — with HTTP status 201, not a duplicate. Reconcile by idempotency_key if you need to detect replays on your side.