Skip to main content
POST
/
metrics
Create a new metric
curl --request POST \
  --url https://api-m.paypal.com/v1/commerce/billing/metrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "API Requests",
  "code": "api_requests",
  "aggregation_type": "COUNT"
}'
{
  "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"
}

Authorizations

​
Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Body

application/json
​
name
string
required

Descriptive name of the metric that represents a pricing component of your application. This is primarily used for display purposes in the user interface.

​
code
string
required

Unique code used to identify the metric within your system. This code is used in API requests to associate events with the correct metric and must be unique across all metrics. Once created, this code cannot be changed.

​
aggregation_type
enum<string> | null
required

Aggregation type for the metric

Available options:
COUNT,
SUM,
MAX,
COUNT_DISTINCT,
LATEST
Example:

"SUM"

​
type
enum<string>
default:RECURRING

Type of metric, either 'metered' for usage-based or 'recurring' for fixed periodic charges.

Available options:
METERED,
RECURRING
Example:

"METERED"

​
description
string

Optional detailed description of the metric that provides additional context about what the metric measures and how it's used. This information is for internal use and helps document the purpose of the metric.

​
aggregation_field
string

Property name within the event payload that will be used for aggregating usage data. This field specifies which value from the event should be used for calculations. It is required for aggregation types like 'SUM', 'MAX', and other types that operate on values, but not required for 'COUNT' aggregation.

​
field_filters
object[]

Response

Metric created successfully

​
name
string
required

Descriptive name of the metric that represents a pricing component of your application. This is primarily used for display purposes in the user interface.

​
code
string
required

Unique code used to identify the metric within your system. This code is used in API requests to associate events with the correct metric and must be unique across all metrics. Once created, this code cannot be changed.

​
aggregation_type
enum<string> | null
required

Aggregation type for the metric

Available options:
COUNT,
SUM,
MAX,
COUNT_DISTINCT,
LATEST
Example:

"SUM"

​
id
string
required

Unique identifier of the metric, automatically generated by the system upon creation. This ID is used internally to track the metric and cannot be modified.

​
created_at
string<date-time>
required

The date and time when the metric was created. ISO 8601 format with timezone. Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

​
type
enum<string>
default:RECURRING

Type of metric, either 'metered' for usage-based or 'recurring' for fixed periodic charges.

Available options:
METERED,
RECURRING
Example:

"METERED"

​
description
string

Optional detailed description of the metric that provides additional context about what the metric measures and how it's used. This information is for internal use and helps document the purpose of the metric.

​
aggregation_field
string

Property name within the event payload that will be used for aggregating usage data. This field specifies which value from the event should be used for calculations. It is required for aggregation types like 'SUM', 'MAX', and other types that operate on values, but not required for 'COUNT' aggregation.

​
field_filters
object[]
​
updated_at
string<date-time>

The date and time when the metric was last updated. ISO 8601 format with timezone. Date and time in ISO 8601 format.

Example:

"2023-10-01T12:00:00Z"

⌘I