Skip to main content
Usage events track what a subscriber consumes under a subscription so Retempo can aggregate metered billing accurately. Each event records a discrete action — an API call, a generated token, a processed document — identified by an eventKey and a quantity. You can attach usage events to an open invoice for precise per-period billing, or leave invoiceId unset and reconcile later. 
POST https://api.retempo.xyz/api/v1/usage-events

​
Request Body

​
serviceId
string
required
The ID of the service the usage occurred on.
​
subscriptionId
string
required
The ID of the subscription this usage belongs to. Must belong to the specified serviceId and userId.
​
userId
string
required
The ID of the subscriber who generated the usage.
​
eventKey
string
required
A string identifier for the type of usage being recorded (e.g. api_request, token_generated). The combination of subscriptionId + eventKey must be unique — submitting the same pair twice returns a 409.
​
quantity
string | number
required
The amount consumed. Pass as a decimal string (e.g. "1000.000000") or a number. Must be a non-negative value.
​
invoiceId
string
The ID of an invoice to associate with this usage event. If provided, the invoice must belong to the same serviceId and userId. Optional — omit to reconcile usage to an invoice later.
​
occurredAt
string
An ISO 8601 datetime string for when the usage occurred. Defaults to the time of the API call if omitted. Pass this to backfill historical usage.

​
Response

A successful request returns HTTP 201 Created with the new usage event object and all related records.
​
usageEvent
object
The newly recorded usage event with related records.

​
201 — Usage event recorded

{
  "usageEvent": {
    "id": "clz1usage333",
    "serviceId": "clz1abc2def3ghi4",
    "subscriptionId": "clz1sub444",
    "userId": "clz1user111",
    "invoiceId": "clz1invoice999",
    "eventKey": "token_generated",
    "quantity": "1000.000000",
    "occurredAt": "2025-06-01T10:25:00.000Z",
    "createdAt": "2025-06-01T10:25:00.000Z",
    "invoice": {
      "id": "clz1invoice999",
      "status": "OPEN",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "service": {
      "id": "clz1abc2def3ghi4",
      "name": "DataStream Pro"
    },
    "subscription": {
      "id": "clz1sub444"
    },
    "user": {
      "id": "clz1user111",
      "email": "subscriber@example.com"
    }
  }
}

​
Example Request

curl -X POST https://api.retempo.xyz/api/v1/usage-events \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "clz1abc2def3ghi4",
    "subscriptionId": "clz1sub444",
    "userId": "clz1user111",
    "eventKey": "token_generated",
    "quantity": "1000.000000",
    "invoiceId": "clz1invoice999",
    "occurredAt": "2025-06-01T10:25:00.000Z"
  }'

​
Error Codes

StatusMessageCondition
400 Bad RequestserviceId is required.serviceId was omitted.
400 Bad RequestsubscriptionId is required.subscriptionId was omitted.
400 Bad RequestuserId is required.userId was omitted.
400 Bad RequesteventKey is required.eventKey was omitted.
400 Bad Requestquantity is required.quantity was omitted.
400 Bad RequestInvoice does not match the usage event service and user.The provided invoiceId belongs to a different service or user.
404 Not FoundSubscription was not found for the service and user.The subscription does not exist or does not belong to the specified service and user.
409 ConflictA database record with these unique fields already exists.The subscriptionId + eventKey combination has already been recorded.
The combination of subscriptionId + eventKey must be unique. Use different eventKey values to track different action types within the same subscription. Duplicate submissions return a 409 error.
Pass occurredAt in ISO 8601 format to backfill usage events that occurred before the API call. This lets you report usage accurately even when your system processes events asynchronously or in batches.