Create metrics - Paypal Docs

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.

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.

Type	Description	Use case
`COUNT`	Counts total items	When you need a simple total, like API calls or transactions.
`COUNT_DISTINCT`	Counts unique values in an events data set	When you want to track distinct users, devices, or IDs.
`SUM`	Adds up values in a data set	When you want a total amount, such as data usage or time spent.
`MAX`	Finds the highest value in a data set	When you need to know the peak value, like maximum storage or highest transaction.
`LATEST`	Uses the most recent value in a data set	When only the current or last value matters, like current balance or latest status.

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 Requests",
    "code": "api_requests",
    "type": "METERED",
    "description": "Measures the total number of API requests made",
    "aggregation_type": "COUNT",
    "field_filters": [
        {
            "key": "region",
            "values": [
                "us-east-1",
                "us-west-1",
                "eu-west-1"
            ]
        }
    ]
}'

Request body parameters

Parameter name	Description
`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	Array of filter objects to include only specific events. See Field filters for more information.
`field_filters[].key` Required when field_filters[] provided, string	Property name to filter on.
`field_filters[].values` Required when field_filters[] provided, array	Array of values to match for the specified key.

Response parameters

This section documents only the response parameters relevant for the next step. For the exhaustive list of response fields, see API reference.

Parameter name	Description and further action
`id` string	Unique identifier for the metric. Use this `id` to reference the metric in future operations, such as creating pricing plans.
`code` string	Unique code for the metric. Use this `code` in future operations, such as managing the metric.

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"]
    }
  ]
}'

6. Manage metrics

You can update metric configurations when adjusting aggregation methods, modifying field filters, or changing metric descriptions. To review a metric’s current configuration, call the Get metric details endpoint.

Metric attribute	Updatable	Possible management options	Impact on existing plans
Metric name	Yes	Update metric details - modify display name	No impact - display only
Metric description	Yes	Update metric details - modify metric description	No impact - display only
Aggregation type	Yes	Update metric details - modify calculation method	Affects usage calculations for all plans using this metric
Aggregation field	Yes	Update metric details - modify event property used for aggregation	Affects usage calculations for all plans using this metric
Field filters	Yes	Update metric details - modify event filtering rules	Affects which events count toward usage
Metric code	No	Metric cannot be modified - unique identifier remains permanent	N/A - cannot be modified
Metric type	No	Metric cannot be modified - type (METERED or RECURRING) is permanent	N/A - cannot be modified

Usage-based Billing

​1. Decide the event to track

​2. Decide the metric type

​3. Decide the aggregation type and aggregation field

​4. Create metrics

​Request body parameters

​Response parameters

​5. Filter aggregation field values

​6. Manage metrics

1. Decide the event to track

2. Decide the metric type

3. Decide the aggregation type and aggregation field

4. Create metrics

Request body parameters

Response parameters

5. Filter aggregation field values

6. Manage metrics