> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.tabs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tabs.com/_mcp/server. # Create an event POST https://usage-events.prod.api.tabsplatform.com/v1/events Content-Type: application/json 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. Reference: https://docs.tabs.com/api-reference/events/ingest-event ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: Tabs External API version: 1.0.0 paths: /v1/events: post: operationId: ingest-event summary: Create an event description: >- 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. tags: - events parameters: - name: Authorization in: header required: true schema: type: string responses: '200': description: Event created successfully content: application/json: schema: $ref: '#/components/schemas/EventCreateResponse' '400': description: Bad request - Invalid event data or duplicate idempotency key content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '422': description: Unprocessable Entity - Validation errors content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/EventCreateRequest' servers: - url: https://usage-events.prod.api.tabsplatform.com description: https://integrators.prod.api.tabsplatform.com components: schemas: EventCreateRequestMetadata: type: object properties: {} description: Optional metadata in JSON format title: EventCreateRequestMetadata EventCreateRequest: type: object properties: customerId: type: string format: uuid description: Tabs Customer ID - must be a valid UUID v4 eventTypeId: type: string format: uuid description: Type of event being recorded - must be a valid UUID v4 datetime: type: string format: date-time description: >- Timestamp when the event occurred (UTC) (format: ISO-8601 datetime string) idempotencyKey: type: string format: uuid description: >- Unique key to prevent duplicate event processing - must be a valid UUID v4 value: type: number format: double description: Numeric value of the event differentiator: type: string description: >- 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: type: string description: >- Optional key to split events into a new invoice; the split key will be appended to the new invoice number metadata: type: object additionalProperties: $ref: '#/components/schemas/EventCreateRequestMetadata' description: Optional metadata in JSON format required: - customerId - eventTypeId - datetime - idempotencyKey - value description: Event data to be ingested title: EventCreateRequest EventResponseMetadata: type: object properties: {} description: Optional metadata in JSON format title: EventResponseMetadata EventResponse: type: object properties: customerId: type: string format: uuid description: Tabs Customer ID - must be a valid UUID v4 eventTypeId: type: string format: uuid description: Type of event being recorded - must be a valid UUID v4 datetime: type: string format: date-time description: >- Timestamp when the event occurred (UTC) (format: ISO-8601 datetime string) idempotencyKey: type: string format: uuid description: >- Unique key to prevent duplicate event processing - must be a valid UUID v4 value: type: number format: double description: Numeric value of the event differentiator: type: string description: >- 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: type: string description: >- Optional key to split events into a new invoice; the split key will be appended to the new invoice number parentEventId: type: string format: uuid description: >- Parent event ID - the idempotency key of the original event that was deleted (only present in DELETE responses) metadata: type: object additionalProperties: $ref: '#/components/schemas/EventResponseMetadata' description: Optional metadata in JSON format description: Event response data title: EventResponse EventData: type: object properties: events: $ref: '#/components/schemas/EventResponse' description: Event data wrapper title: EventData EventCreateResponse: type: object properties: success: type: boolean description: Indicates if the operation was successful message: type: string description: Human-readable message about the operation result data: $ref: '#/components/schemas/EventData' description: Response for successful event creation title: EventCreateResponse ErrorDetail: type: object properties: code: type: integer description: Error code message: type: string description: Error message details: type: object additionalProperties: type: array items: type: string description: Map of field names to array of error messages description: Detailed error information title: ErrorDetail ValidationErrorResponse: type: object properties: success: type: boolean description: Indicates if the operation was successful message: type: string description: Human-readable error message error: $ref: '#/components/schemas/ErrorDetail' description: Error response for validation failures title: ValidationErrorResponse UnauthorizedResponse: type: object properties: statusCode: type: integer description: HTTP status code message: type: string description: Error message timestamp: type: string description: Timestamp when the error occurred path: type: string description: Request path method: type: string description: HTTP method description: Unauthorized error response title: UnauthorizedResponse RateLimitResponse: type: object properties: statusCode: type: integer description: HTTP status code message: type: string description: Error message timestamp: type: string description: Timestamp when the error occurred path: type: string description: Request path method: type: string description: HTTP method retryAfter: type: integer description: Number of seconds to wait before retrying description: Rate limit exceeded error response title: RateLimitResponse securitySchemes: custom-header: type: apiKey in: header name: Authorization ``` ## Examples **Request** ```json { "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 } ``` **Response** ```json { "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": "018c1234-5678-7abc-def0-123456789abc", "value": 1, "differentiator": "mobile", "invoiceSplitKey": "invoice-123", "manufacturerId": "550e8400-e29b-41d4-a716-446655440000" } } } ``` **SDK Code** ```python Success Response import requests url = "https://usage-events.prod.api.tabsplatform.com/v1/events" payload = { "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 } headers = { "Authorization": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Success Response const url = 'https://usage-events.prod.api.tabsplatform.com/v1/events'; const options = { method: 'POST', headers: {Authorization: '', 'Content-Type': 'application/json'}, body: '{"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}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Success Response package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://usage-events.prod.api.tabsplatform.com/v1/events" payload := strings.NewReader("{\n \"customerId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"eventTypeId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"datetime\": \"2024-01-15T10:30:00Z\",\n \"idempotencyKey\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"value\": 1.5\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Success Response require 'uri' require 'net/http' url = URI("https://usage-events.prod.api.tabsplatform.com/v1/events") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"customerId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"eventTypeId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"datetime\": \"2024-01-15T10:30:00Z\",\n \"idempotencyKey\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"value\": 1.5\n}" response = http.request(request) puts response.read_body ``` ```java Success Response import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://usage-events.prod.api.tabsplatform.com/v1/events") .header("Authorization", "") .header("Content-Type", "application/json") .body("{\n \"customerId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"eventTypeId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"datetime\": \"2024-01-15T10:30:00Z\",\n \"idempotencyKey\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"value\": 1.5\n}") .asString(); ``` ```php Success Response request('POST', 'https://usage-events.prod.api.tabsplatform.com/v1/events', [ 'body' => '{ "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 }', 'headers' => [ 'Authorization' => '', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Success Response using RestSharp; var client = new RestClient("https://usage-events.prod.api.tabsplatform.com/v1/events"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"customerId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"eventTypeId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"datetime\": \"2024-01-15T10:30:00Z\",\n \"idempotencyKey\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"value\": 1.5\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Success Response import Foundation let headers = [ "Authorization": "", "Content-Type": "application/json" ] let parameters = [ "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 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://usage-events.prod.api.tabsplatform.com/v1/events")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```