Ingest usage events

Send usage events for billing. Accepts a single event or a batch of up to 1000 events.

Single event: Send the event object directly in the request body. Batch: Wrap events in an events array.

Events are matched to meters by name (event name) or meter_id. At least one of customer_id, external_customer_id, or subscription_id is required.

Idempotency: provide idempotency_key per event. The key is unique per merchant forever; repeats return duplicate and do not create another billable event.

Attribution: prefer external_customer_id when your system owns customer identifiers. Unknown external IDs fail fast instead of creating orphan usage.

Currency: each subscription has one currency. Usage attributed to that subscription is interpreted in that currency; RevKeen does not perform FX conversion in the metering layer.

Related endpoints

• GET /usage-events — Query usage events
• POST /usage-events/dry-run — Dry-run usage events
• GET /usage-events/aggregate/{meterId} — Get aggregated usage

Common errors

• 400 invalid_request — malformed payload or failed validation.
• 401 unauthenticated — missing, malformed, or revoked API key.

Idempotency

Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.

curl -X POST "https://api.revkeen.com/v2/usage-events" \
  -H "x-api-key: $REVKEEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api_call",
    "customer_id": "string",
    "external_customer_id": "usr_123",
    "subscription_id": "string",
    "meter_id": "string",
    "quantity": 1,
    "timestamp": "2026-03-14T10:30:00Z",
    "idempotency_key": "evt_unique_123",
    "metadata": {}
  }'

{
  "object": "usage_event_batch_result",
  "summary": {
    "ingested": 0,
    "duplicate": 0,
    "skipped": 0,
    "failed": 0
  },
  "data": [
    {
      "index": 0,
      "status": "ingested",
      "id": "string",
      "reason": "string"
    }
  ]
}

{
  "object": "usage_event_batch_result",
  "summary": {
    "ingested": 0,
    "duplicate": 0,
    "skipped": 0,
    "failed": 0
  },
  "data": [
    {
      "index": 0,
      "status": "ingested",
      "id": "string",
      "reason": "string"
    }
  ]
}

{
  "object": "usage_event_batch_result",
  "summary": {
    "ingested": 0,
    "duplicate": 0,
    "skipped": 0,
    "failed": 0
  },
  "data": [
    {
      "index": 0,
      "status": "ingested",
      "id": "string",
      "reason": "string"
    }
  ]
}

{
  "error": "string"
}

{
  "error": "string"
}