Skip to main content
With PayPal’s Usage-based Billing, you can charge your customers based on how much they use a certain feature in your system. An event is an action your customer does while using your system. For example, placing an API call is an event. A metric defines how to aggregate events data and arrive at the billable usage. For example, a metric definition can count the number of API calls a customer places in a billing period. This becomes the usage against which you bill your customers. To create and configure metrics:
  1. Decide the event to track
  2. Decide the metric type
  3. Decide the aggregation type and aggregation field
  4. Create metrics
  5. (Optional) Filter aggregation field values

​
1. Decide the event to track

Before you create metrics, choose which event you want to track and the event details (event properties) you require. For most aggregation methods, you must include the event property name in the API call to create metrics.

​
2. Decide the metric type

Based on your business use case, decide on one of the following metric types:
  • Metered metric: Customers are charged based on exactly how much of a feature they use within a specific billing period. The usage resets to zero each cycle and customers pay only for what they use in that period. For example, a metric that calculates usage based on the number of API calls placed in a month.
  • Recurring metric: Customers are charged for a usage that persists across billing periods. The usage accumulates or remains steady until modified. For example, a metric that calculates usage as the total storage space utilized.
You must pass the metric type in the API call to create metrics.

​
3. Decide the aggregation type and aggregation field

Aggregation type determines how the metric aggregates events data and calculates usage. Based on your business use case, choose an aggregation type, from the following.
TypeDescriptionUse case
COUNTCounts total itemsWhen you need a simple total, like API calls or transactions.
COUNT_DISTINCTCounts unique values in an events data setWhen you want to track distinct users, devices, or IDs.
SUMAdds up values in a data setWhen you want a total amount, such as data usage or time spent.
MAXFinds the highest value in a data setWhen you need to know the peak value, like maximum storage or highest transaction.
LATESTUses the most recent value in a data setWhen only the current or last value matters, like current balance or latest status.
Note: Recurring metrics support only SUM and COUNT_DISTINCT aggregation types.
You can track multiple properties of an event. Aggregation field specifies the specific property on which the selected aggregation type is to be applied. For example, an event for using data storage can contain properties such as storage_gb and region. You can set up a metric that aggregates storage_gb to determine billable usage. In this case, storage_gb is the aggregation field. You must pass the aggregation type in the API call to create metrics.

​
4. Create metrics

Use a valid access token and send a POST request to /v1/commerce/billing/metrics with all required request parameters including metric type, aggregation type, and optional field filters. On successful metric creation, the PayPal server returns a metric ID. 
curl -X POST --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/metrics' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS-TOKEN>' \
--data '{
    "name": "API calls metrics",
    "code": "API_CALLS_METRICS",
    "type": "METERED",
    "description": "API calls",
    "aggregation_type": "COUNT"
}'

​
Request body parameters

Parameter nameDescription
name
Required, string		Descriptive name for the metric.
code
Required, string		Unique identifier to match with event codes.
type
Required, string		Type of metric.

Default value: RECURRING

Possible values: METERED, RECURRING

Note: Choose METERED to reset usage each billing period or RECURRING to accumulate usage.
aggregation_type
Required, string		Defines the calculation method for the metric.

Possible values: COUNT, COUNT_DISTINCT, SUM, MAX, LATEST.

See Aggregation types for more information.
aggregation_field
Required when aggregation_type is SUM, COUNT_DISTINCT, MAX, or LATEST, string		Event property to use for usage calculation.
description
string		Additional details about what the metric measures.
field_filters
array		Filters to include only specific events.

Each filter is an object with:
- key (string): property name
- values (array of strings): values to match.

See Field filters for more information.

​
Response parameters

Note: This section documents only the response parameters relevant for the next step. For the exhaustive list of response fields, see API reference.
Parameter nameDescription and further action
id
string		Unique identifier for the metric.
Use this id to reference the metric in future operations, such as creating a pricing plan.

​
5. Filter aggregation field values

Field filters let you include only specific events or data in your metric calculation. The system only includes events that match all your filter rules. For each filter, choose a property name (key) and the values you want to match. Common ways to use filters and samples:
  • By region: Track usage across different geographic locations
  • By performance tier: Separate different service levels
  • By token type: Distinguish between different AI processing types
  • By feature: Track premium vs standard features
  • By status: Count only successful operations
curl -X POST --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
  "name": "Database Usage - Europe",
  "code": "DB_USAGE_EU",
  "type": "METERED",
  "description": "Database storage usage in European regions",
  "aggregation_type": "SUM",
  "aggregation_field": "storage_gb",
  "field_filters": [
    {
      "key": "region",
      "values": ["europe", "africa"]
    }
  ]
}'
⌘I