v1

latestOpenAPI 3.0.02026-07-24102143224.1 KB

Events

Create an event

Creates a new usage event. Requires valid authentication and unique idempotency key. Reach out to your account manager if you would like to participate in the Beta for the new Usage API.

post/v1/events

Request body

customerIdstring uuid required

Tabs Customer ID - must be a valid UUID v4

eventTypeIdstring uuid required

Type of event being recorded - must be a valid UUID v4

datetimestring date-time required

Timestamp when the event occurred (UTC) (format: ISO-8601 datetime string)

idempotencyKeystring uuid required

Unique key to prevent duplicate event processing - must be a valid UUID v4

valuenumber double required

Numeric value of the event

differentiatorstring

Optional key to separate events with the same event type and customer into different invoice line items; differentiator will be appended to the description of the new invoice line item

invoiceSplitKeystring

Optional key to split events into a new invoice; the split key will be appended to the new invoice number

metadataobject

Optional metadata in JSON format

Example request

{
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "eventTypeId": "550e8400-e29b-41d4-a716-446655440000",
  "datetime": "2024-01-15T10:30:00Z",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "value": 1.5,
  "differentiator": "mobile",
  "invoiceSplitKey": "invoice-123",
  "metadata": {
    "key": "value"
  }
}

Response

Event created successfully

successboolean

Indicates if the operation was successful

messagestring

Human-readable message about the operation result

Example response

{
  "success": true,
  "message": "Event created successfully",
  "data": {
    "events": {
      "customerId": "550e8400-e29b-41d4-a716-446655440000",
      "eventTypeId": "550e8400-e29b-41d4-a716-446655440000",
      "datetime": "2024-01-15T10:30:00Z",
      "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
      "value": 1.5,
      "differentiator": "mobile",
      "invoiceSplitKey": "invoice-123",
      "parentEventId": "018c1234-5678-7abc-def0-123456789000",
      "metadata": {
        "key": "value"
      }
    }
  }
}