Create metrics - Paypal Docs

A metric defines how to aggregate event data and calculate billable usage. An event is an action your customer performs while using your system, such as placing an API call. Metrics connect the following:

Pricing plans that apply pricing models to metric usage for calculating charges.
Usage events that the metric aggregates to determine billable consumption.

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 need to 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 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 need to 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 event data and calculates usage. Based on your business use case, choose an aggregation type from the following.

Aggregation 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 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 need to pass the aggregation type in the API call to create metrics.

4. Create metrics

Use a valid access token and make a POST call to the /v1/commerce/billing/metrics endpoint 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 -L '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 -L '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