Skip to main content
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 must 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, and so on).
  • 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

​
1. Send usage events to PayPal

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

​
Send multiple events

As and when events occur, use a valid access token and send a POST request to /v1/commerce/billing/events with all required request parameters.
Include your billing_tier_id in the request header to enable higher rate limits for high-volume event processing.
On successful event creation, the PayPal server returns an event ID. 
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
  }
}'

​
Request body parameters

Parameter nameDescription
transaction_id
Required, string		Unique identifier that identifies the event. Ensure transaction_id values are unique across all events.
metric_code
Required, string		Unique code that identifies the metric. Use the code you provided when you created the metric.
external_subscription_id
Required, string		Unique identifier that identifies the subscription. Use the external_id you provided when you created the subscription.
timestamp
string		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		Key-value pairs that specify event properties and corresponding usage amounts. The property key you use here (for example, gb for storage or minutes for compute time) must exactly match the aggregation_field value defined in your metric configuration. This ensures PayPal knows which value to aggregate for billing calculations.

​
Send a batch of events

Use a valid access token and send a POST request to /v1/commerce/billing/events/batch with all required request parameters. You can send up to 100 events in a single batch request. On successful batch submission, the PayPal server returns a status confirmation. 
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
      }
    }
  ]
}'

​
Request body parameters

Parameter nameDescription
events
Required, array		Array of event objects. Each event must include the parameters below.
events.transaction_id
Required, string		A unique identifier that identifies the event. Required for each event in the batch. Ensure transaction_id values are unique across all events.
events.metric_code
Required, string		Unique code that identifies the metric. Use the code you provided when you created the metric.
events.external_subscription_id
Required, string		Unique identifier that identifies the subscription. Use the external_id you provided when you created the subscription.
events.timestamp
string		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		Key-value pairs that specify event properties and corresponding usage amounts. The property key you use here (for example, gb for storage or minutes for compute time) must exactly match the aggregation_field value defined in your metric configuration. This ensures PayPal knows which value to aggregate for billing calculations.
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.
  • Solve 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.