---
title: "Create a new usage event"
method: POST
path: "/events"
tags: ["Events"]
---

# Create a new usage event

`POST /events`

## Request

- Base URL: `https://api-m.sandbox.paypal.com`
- URL: `https://api-m.sandbox.paypal.com/events`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `/api/oauth-proxy` scopes: `read`, `write`
- TypeScript: <https://skmtc.dev/paypal/apis/usage-based-billing-api/docs/events/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- EventRequest
  - `transaction_id` string, required: Unique identifier for the transaction associated with the event
  - `external_subscription_id` string, required: External subscription ID associated with the event
  - `metric_code` string, required: Identifier for the targeted metric. This value must match the `code` property of an active metric; otherwise, it will be disregarded during processing.
  - `timestamp` string, date-time: Date and time in ISO 8601 format.
  - `properties` object

## Response `201`

Event created successfully

- EventResponse
  - `transaction_id` string, required: Unique identifier for the transaction associated with the event
  - `external_subscription_id` string, required: External subscription ID associated with the event
  - `metric_code` string, required: Identifier for the targeted metric. This value must match the `code` property of an active metric; otherwise, it will be disregarded during processing.
  - `timestamp` string, date-time: Date and time in ISO 8601 format.
  - `properties` object
  - `id` string: Unique identifier for the event
  - `created_at` string, date-time: Date and time in ISO 8601 format.

## Other responses

- `400`: Bad Request - Invalid input data
- `403`: Authorization failed due to insufficient permissions.
- `422`: Bad Request - Invalid input data
- `500`: Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.dev/paypal/apis/usage-based-billing-api.md) - [All operations](https://skmtc.dev/paypal/apis/usage-based-billing-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paypal/apis/usage-based-billing-api/revisions/22fb46514ac4?raw)