Create metrics - Paypal Docs

Limited Release

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. Include the following parameters:

Parameter	Action
`name` Required, string	Provide a descriptive name that identifies the metric’s purpose.
`code` Required, string	Set a unique code to identify this metric.
`type` Required, string	Set to `METERED` to reset usage each billing period or `RECURRING` to accumulate usage.
`aggregation_type` Required, string	Choose the aggregation type based on your billing use case. See Aggregation types for more information. Possible values: `COUNT`, `COUNT_DISTINCT`, `SUM`, `MAX`, `LATEST`.
`aggregation_field` Required when `aggregation_type` is `SUM`, `COUNT_DISTINCT`, `MAX`, or `LATEST`, string	Set to the event property name that contains the value to aggregate.
`description` string	Provide additional details about what the metric measures.
`field_filters[]` array	Add filter objects to include only specific events. See Field filters for more information.
`field_filters[].key` Required when field_filters[] provided, string	Set to the event property name to filter by.
`field_filters[].values` Required when field_filters[] provided, array	Provide an array of values to include in the metric calculation.

For information on all parameters, see API reference.

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

{
    "id": "bm_01H2XT1G7N8E2JHJKBVPDS0TQD",
    "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"
            ]
        }
    ],
    "created_at": "2023-05-10T14:32:18Z"
}

A successful call returns a 201 Created response. The response includes the following parameters:

Parameter	Description	Further action
`id` string	Unique identifier for the metric.	Use this `id` when creating pricing plans.
`code` string	Unique code for the metric.	Use this `code` when managing the metric.

For information on all parameters, see API reference.

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

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": "Premium GPU Time",
  "code": "GPU_TIME_PREMIUM",
  "type": "METERED",
  "description": "GPU compute time for premium GPU instances",
  "aggregation_type": "SUM",
  "aggregation_field": "compute_minutes",
  "field_filters": [
    {
      "key": "gpu_type",
      "values": ["standard_gpu", "premium_gpu"]
    }
  ]
}'

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": "AI Input Tokens",
  "code": "AI_INPUT_TOKENS",
  "type": "METERED",
  "description": "AI tokens consumed for input and cached input processing",
  "aggregation_type": "SUM",
  "aggregation_field": "token_count",
  "field_filters": [
    {
      "key": "token_type",
      "values": ["input", "cached_input"]
    }
  ]
}'

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": "Unique Premium Feature Users",
  "code": "UNIQUE_PREMIUM_USERS",
  "type": "METERED",
  "description": "Counts unique users accessing premium features",
  "aggregation_type": "COUNT_DISTINCT",
  "aggregation_field": "user_id",
  "field_filters": [
    {
      "key": "feature_tier",
      "values": ["premium", "enterprise"]
    }
  ]
}'

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

​1. Decide the event to track

​2. Decide the metric type

​3. Decide the aggregation type and aggregation field

​4. Create metrics

​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

5. Filter aggregation field values

6. Manage metrics