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.
To record usage events: Send multiple single-events: Submit every usage event in real-time.
Or
Send a batch of events: Submit multiple events at once for high-volume scenarios.

​
Prerequisites

​
1. Send usage events to PayPal

​
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.
Important: 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. This value must match the code property of an active metric.
external_subscription_id
Required, string		Unique identifier that identifies the subscription. It is the ID you enter when creating a 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. hods. 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.
Note: For the exhaustive list of response fields, see API reference.

​
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		A unique code that identifies the metric. This value must match the code property of an active metric. Required for each event in the batch.
events.external_subscription_id
Required, string		Unique identifier that identifies the subscription. It is the ID you enter when creating a 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.
Note: For the exhaustive list of response fields, see API reference.
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.
⌘I