Skip to main content
POST
/
events
Create a new usage event
curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_id": "txn_1234567890abcdef",
  "external_subscription_id": "sub_1234567890abcdef",
  "metric_code": "event_code_123456",
  "timestamp": "2023-01-01T00:00:00Z",
  "properties": {}
}
'
{
  "transaction_id": "event_1753818829",
  "metric_code": "91624203-791a-4639-8c86-4693948b3a41",
  "external_subscription_id": "d2d628e8-e7fb-412f-b09c-7f70ee58b50a",
  "timestamp": "2025-07-29T12:53:49.076-07:00",
  "properties": {
    "gb": 10
  },
  "id": "d80447f2-0f34-4612-86ae-152160dc66c5",
  "created_at": "2025-07-29T12:53:49-07:00"
}

Authorizations

​
Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Body

application/json
​
transaction_id
string
required

Unique identifier for the transaction associated with the event

Example:

"txn_1234567890abcdef"

​
external_subscription_id
string
required

External subscription ID associated with the event

Example:

"sub_1234567890abcdef"

​
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.

Example:

"event_code_123456"

​
timestamp
string<date-time>

Timestamp when the event occurred

Example:

"2023-01-01T00:00:00Z"

​
properties
object

Response

Event created successfully

​
transaction_id
string
required

Unique identifier for the transaction associated with the event

Example:

"txn_1234567890abcdef"

​
external_subscription_id
string
required

External subscription ID associated with the event

Example:

"sub_1234567890abcdef"

​
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.

Example:

"event_code_123456"

​
timestamp
string<date-time>

Timestamp when the event occurred

Example:

"2023-01-01T00:00:00Z"

​
properties
object
​
id
string

Unique identifier for the event

Example:

"evt_1234567890abcdef"

​
created_at
string<date-time>

Timestamp when the event was created

Example:

"2023-01-01T00:00:00Z"