---
title: "Create an event"
method: POST
path: "/v1/events"
tags: ["Events"]
---

# Create an event

`POST /v1/events`

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.

## Request body

- EventCreateRequest — Event data to be ingested
  - `customerId` string, uuid, required — Tabs Customer ID - must be a valid UUID v4
  - `eventTypeId` string, uuid, required — Type of event being recorded - must be a valid UUID v4
  - `datetime` string, date-time, required — Timestamp when the event occurred (UTC) (format: ISO-8601 datetime string)
  - `idempotencyKey` string, uuid, required — Unique key to prevent duplicate event processing - must be a valid UUID v4
  - `value` number, double, required — Numeric value of the event
  - `differentiator` string — 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
  - `invoiceSplitKey` string — Optional key to split events into a new invoice; the split key will be appended to the new invoice number
  - `metadata` object — Optional metadata in JSON format

## Response `200`

Event created successfully

- EventCreateResponse — Response for successful event creation
  - `success` boolean — Indicates if the operation was successful
  - `message` string — Human-readable message about the operation result
  - `data` EventData — Event data wrapper
    - `events` EventResponse — Event response data
      - `customerId` string, uuid — Tabs Customer ID - must be a valid UUID v4
      - `eventTypeId` string, uuid — Type of event being recorded - must be a valid UUID v4
      - `datetime` string, date-time — Timestamp when the event occurred (UTC) (format: ISO-8601 datetime string)
      - `idempotencyKey` string, uuid — Unique key to prevent duplicate event processing - must be a valid UUID v4
      - `value` number, double — Numeric value of the event
      - `differentiator` string — 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
      - `invoiceSplitKey` string — Optional key to split events into a new invoice; the split key will be appended to the new invoice number
      - `parentEventId` string, uuid — Parent event ID - the idempotency key of the original event that was deleted (only present in DELETE responses)
      - `metadata` object — Optional metadata in JSON format

## Other responses

- `400` — Bad request - Invalid event data or duplicate idempotency key
- `401` — Unauthorized - Invalid or missing API key
- `422` — Unprocessable Entity - Validation errors
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error

---

[API](https://skmtc.net/tabsplatform/apis/tabs-external-api.md) · [All operations](https://skmtc.net/tabsplatform/apis/tabs-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tabsplatform/tabs-external-api/revisions/7e8885517814/schema)