Skip to main content
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

​
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:
ParameterAction
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
  }
}'
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:
ParameterAction
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
      }
    }
  ]
}'
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.