Custom Metrics API overview

Before you begin

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

Before you can create custom metrics:

1. Make sure you have metrics (e.g., Placed Order) in your account and real event data for those metrics.
2. Use Get Metrics to fetch the set of available metrics in an account and Get Properties for Metric to confirm a metric’s available properties that can be used in custom metric filters.

You’ll then be able to use the Custom Metrics API to create custom metrics based on the existing metrics in an account.

Using custom metrics

By default, Klaviyo provides metrics that track your business’s performance and measure success (e.g., a Placed Order event from a Klaviyo e-commerce integration). However, there may be instances where you need to create custom metrics to more accurately capture how your business runs. For examples of useful custom metrics, check out our strategic guide on using custom metrics.

Our Custom Metrics API allows you to manage custom metrics programmatically, i.e., custom conversion metrics that are based off of metrics in your account (native Klaviyo, integration-specific, and API metrics).

📘

Standard accounts can only have 1 custom metric. Upgrade to Klaviyo’s Advanced KDP or Marketing Analytics plan to create up to 50 custom metrics. Advanced KDP also automatically detects and provides default custom metrics based on an account's active integrations. To learn more about these plans, visit our billing guide.

Use cases

Here are some example use cases supported by the Custom Metrics API:

• Create a custom metric to better model the important conversion metrics that are specific to an account's business, e.g., a custom metric based on Placed Order that filters out recurring subscriptions or an “Ordered Product - Retail” metric for products ordered online (vs. in-person).
• Update the definition for a custom metric.
• Use a custom metric "Revenue" as the conversion metric in our campaign & flow Reporting APIs to understand attributed revenue for flows & campaigns (see Use the Reporting API on custom metrics).
• Delete a custom metric.
• Fetch metrics related to a custom metric, i.e., metrics that define a given custom metric.

📘

After you create your own custom metrics (e.g., a custom metric based on Placed Order that excludes subscriptions), applicable reporting will be updated in the UI.

Data model

A custom metric has the following structure:

• id

  The ID of the custom metric.

• attributes

  • name

    The name of the custom metric.

  • definition

    The definition of a custom metric. It is composed of a list of metric_groups, which are combined with a logical AND.

    • aggregation_method

      Method of aggregation for custom metric measurements (value or count). A metric with a value aggregation method is treated as a revenue metric, e.g., Placed Order; the metric must have a "$value" property to use this kind of aggregation. A metric with a count aggregation method is used for reporting on the count of the metric.

    • metric_groups

      An array of objects that defines which events the custom metric should include. For each metric group, you must provide an identifier for an existing metric, e.g., Placed Order. Then, you may filter the metric’s properties to further define which events should be included.

      • metric_id

        The ID of the metric that composes the custom metric.

      • metric_filters

        An optional array of objects for filtering on properties of the metric.

        • property

          The property for the given metric that you’d like to filter on, e.g., ItemNames.

        • filter

          The filter that is to be applied to the property, e.g., a filter that checks if a specific item is present in a list. See the API reference documentation for a complete list of filters.

      • value_property

        The property that calculates the conversion value (only used for custom metrics with an aggregation_method of value). If null, the default $value property will be used.

🚧

Each custom metric you create can be composed of up to 5 different metrics and up to 3 metric filters per metric group. (see Limitations for more information).

Get Custom Metrics

The Get Custom Metrics endpoint is useful for retrieving information about custom metrics in an account. You can include related metrics in your response and use sparse fieldsets to request only specific fields in your response, e.g., only show aggregation method fields for custom metrics in your account. Similarly, Get Custom Metric is useful for fetching data for a given custom metric.

Use sparse fieldsets to only show the desired fields in your response. See the example request to Get Custom Metrics below:

curl --request GET \
     --url https://a.klaviyo.com/api/custom-metrics/?fields[custom-metric]=name,definition.aggregation_method \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2025-04-15'

{
    "data": [
        {
            "type": "custom-metric",
            "id": "01J2EZE52CT203GP5BGJPP9H5A",
            "attributes": {
                "name": "Placed Order - Online",
                "definition": {
                    "metric_groups": [
                        {
                            "metric_id": "SDXgcj",
                            "metric_filters": [
                                {
                                    "property": "Source Name",
                                    "filter": {
                                        "type": "list",
                                        "operator": "not-contains",
                                        "value": "pos"
                                    }
                                }
                            ],
                            "value_property": "$value"
                        }
                    ],
                    "aggregation_method": "value"
                }
            },
            "relationships": {
                "metrics": {
                    "data": [
                        {
                            "type": "metric",
                            "id": "SDXgcj"
                        }
                    ],
                    "links": {
                        "self": "https://a.klaviyo.com/api/custom-metrics/01J2EZE52CT203GP5BGJPP9H5A/relationships/metrics/",
                        "related": "https://a.klaviyo.com/api/custom-metrics/01J2EZE52CT203GP5BGJPP9H5A/metrics/"
                    }
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/custom-metrics/01J2EZE52CT203GP5BGJPP9H5A/"
            }
        },
        {
            "type": "custom-metric",
            "id": "01J2EZE4YJQCCZ4NTTA6RSPY24",
            "attributes": {
                "name": "Ordered Product - Count",
                "definition": {
                    "metric_groups": [
                        {
                            "metric_id": "RaFtaN",
                            "metric_filters": [],
                            "value_property": null
                        }
                    ],
                    "aggregation_method": "count"
                }
            },
            "relationships": {
                "metrics": {
                    "data": [
                        {
                            "type": "metric",
                            "id": "RaFtaN"
                        }
                    ],
                    "links": {
                        "self": "https://a.klaviyo.com/api/custom-metrics/01J2EZE4YJQCCZ4NTTA6RSPY24/relationships/metrics/",
                        "related": "https://a.klaviyo.com/api/custom-metrics/01J2EZE4YJQCCZ4NTTA6RSPY24/metrics/"
                    }
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/custom-metrics/01J2EZE4YJQCCZ4NTTA6RSPY24/"
            }
        }
    ],
    "links": {
        "self": "https://a.klaviyo.com/api/custom-metrics?fields[custom-metric]=name,definition.metric_groups,definition.aggregation_method"
    }
}

Create Custom Metric

To create a custom metric, you’ll need to provide a definition object that includes the aggregation method and metric groups that define what events your custom metric includes.

The example request payload below for Create Custom Metric creates a custom metric based on Placed Order that filters out recurring subscriptions:

{
    "data": {
        "type": "custom-metric",
        "attributes": {
            "name": "Placed Order - Ecommerce",
            "definition": {
                "aggregation_method": "value",
                "metric_groups": [{
                    "metric_id": "T4kAe8",
                    "value_property": "Revenue",
                    "metric_filters": [{
                        "property": "Source Name",
                        "filter": {
                            "type": "string",
                            "operator": "does not equal",
                            "value": "subscription"
                        }
                    }]
                }]
            }
        }
    }
}

Here’s how the resulting custom metric definition appears in Klaviyo’s custom metric builder (Metrics > Create custom metric):

Use the Reporting API on custom metrics

You can use the Reporting API on custom metrics to retrieve attributed value for campaigns and flows.

1. Use Get Custom Metrics to get the metric ID for the custom metric you’d like to use for calculating conversion-based statistics.
2. Then, create a campaigns or flows report to request statistics for a given campaign or flow using the Reporting API.

The example below is a request payload to Query Campaign Values that fetches campaign performance data using a custom metric for calculating conversion-based statistics:

curl --request POST \
     --url https://a.klaviyo.com/api/campaign-values-reports/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2025-04-15' \
     --data '
{
  "data": {
    "type": "campaign-values-report",
    "attributes": {
      "timeframe": {
        "key": "last_12_months"
      },
      "conversion_metric_id": "01J2EZE52CT203GP5BGJPP9H5A",
      "filter": "equals(campaign_id",\"01GMRWDSA0ARTAKE1SFX8JGXAY\")",

      "statistics": [
        "opens",
        "open_rate"
      ]
    }
  }
}
'

Limitations

• Accounts can only have one custom metric. To access up to 50 custom metrics, the Advanced Klaviyo Data Platform is required.
• A custom metric group can contain up to 5 metrics.
• A metric defined within the custom metric group can have up to 3 filters on its properties.

Common errors

Additional resources

• How to configure custom conversion metrics
• Understanding when and how to use custom conversion metrics