Record metric usage due to events

Limited Release

An event is an action your customer takes while using your product or service. For example, making an API call, uploading a file, or using storage space are all events. Each event uses some amount of a metric. This metric usage affects your billing. You need to record each event’s metric usage with PayPal. PayPal uses this data to track usage and calculate charges. This process of recording usage is called metering. An event connects the following entities:

The metric that measures what you charge for (API calls, storage GB).
The customer’s subscription that determines their pricing plan and billing cycle.
The actual metric usage that an event consumes. PayPal aggregates this data to calculate charges.

Prerequisites

Create and set up all metrics that define how events are aggregated for billing.
Register the customers to whom you want to track usage events.
Create subscriptions that link customers to your pricing plans.

1. Send usage events to PayPal

You can send usage events using one of the following methods:

Send multiple events

Use a valid access token and make a POST call to the /v1/commerce/billing/events endpoint. Include the following parameters:

Parameter	Action
`transaction_id` Required, string	Set a unique identifier for this event. Ensure values are unique across all events.
`metric_code` Required, string	Set to the `code` returned when you created the metric.
`external_subscription_id` Required, string	Set to the `external_id` returned when you created the subscription.
`timestamp` string	Set the ISO 8601 timestamp when the event occurred. If not provided, PayPal uses the current time.
`properties` Required for `SUM`, `MAX`, `COUNT_DISTINCT`, and `LATEST` aggregation types, object	Provide key-value pairs for event properties and usage amounts. The property key (for example, `gb` or `minutes`) must match the `aggregation_field` from your metric configuration.

For information on all parameters, see API reference.

Include your billing tier ID in the request header to enable higher rate limits for high-volume event processing.

curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/events' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-H 'X-Billing-Tier-Id: <BILLING-TIER-ID>' \
-d '{
  "transaction_id": "event_1753818829",
  "external_subscription_id": "d2d628e8-e7fb-412f-b09c-7f70ee58b50a",
  "metric_code": "91624203-791a-4639-8c86-4693948b3a41",
  "timestamp": "2025-07-29T12:53:49.076-07:00",
  "properties": {
    "gb": 10
  }
}'

{
    "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"
}

A successful call returns a 201 Created response with the event ID.

Send a batch of events

Use a valid access token and make a POST call to the /v1/commerce/billing/events/batch endpoint. You can send up to 100 events in a single batch request. Include the following parameters:

Parameter	Action
`events` Required, array	Provide an array of event objects (up to 100 events per batch).
`events.transaction_id` Required, string	Set a unique identifier for each event. Ensure values are unique across all events.
`events.metric_code` Required, string	Set to the `code` returned when you created the metric.
`events.external_subscription_id` Required, string	Set to the `external_id` returned when you created the subscription.
`events.timestamp` string	Set the ISO 8601 timestamp when the event occurred. If not provided, PayPal uses the current time.
`events.properties` Required for `SUM`, `MAX`, `COUNT_DISTINCT`, and `LATEST` aggregation types, object	Provide key-value pairs for event properties and usage amounts. The property key (for example, `gb` or `minutes`) must match the `aggregation_field` from your metric configuration.

For information on all parameters, see API reference.

curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/events/batch' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "events": [
    {
      "transaction_id": "event_t1_1753838783",
      "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41",
      "metric_code": "Billable_Metrics_1753827008",
      "timestamp": "2023-01-01T00:00:00Z",
      "properties": {
        "gb": 10
      }
    },
    {
      "transaction_id": "event_t2_1753838783",
      "external_subscription_id": "91624203-791a-4639-8c86-4693948b3a41",
      "metric_code": "Billable_Metrics_1753827008",
      "timestamp": "2023-01-01T00:00:00Z",
      "properties": {
        "gb": 10
      }
    }
  ]
}'

{
    "status": "ACCEPTED",
    "results": {
        "success_count": 2,
        "error_count": 0
    }
}

A successful call returns a 201 Created response with the status confirmation. After you record events and meter usage, PayPal converts this metered data into charges for your customers and bills them. See Understand billing.

2. Optional: Audit usage events

You can retrieve and audit the usage events recorded with PayPal to:

Ensure billing accuracy.
Resolve customer disputes.
Validate that all events were saved correctly.
Ensure that the events recorded match your own tracking systems.

For information on how to do this, see Audit usage events.

​Prerequisites

​1. Send usage events to PayPal

​Send multiple events

​Send a batch of events

​2. Optional: Audit usage events

Prerequisites

1. Send usage events to PayPal

Send multiple events

Send a batch of events

2. Optional: Audit usage events