Get metrics data for your account using the API

What's new?

We've added a new set of operations under the /metrics path to the Paddle API. They return timeseries data for key business metrics, aggregated by day across a date range you specify.

All operations require the new metrics.read permission.

How it works

Metrics are a way of querying aggregated data from your Paddle account. Unlike reports, which export a historical snapshot of your entities as a CSV, metrics return timeseries data directly in the API response.

You can use them to build dashboards, reporting tools, and any integration that needs to track trends over time without pulling and aggregating raw entity data yourself.

When working with metrics, you can use the from (inclusive) and to (exclusive) query parameters to set the date range. Paddle returns one datapoint per day in that range, each with a timestamp and a set of value fields depending on the metric.

The shape of the datapoint depends on the metric:

• Amount-based
  Metrics related to revenue return an amount field, expressed as a string representing a non-decimal amount in the smallest currency unit.
• Count-based
  Metrics related to subscriber or event counts return a count field.
• Mixed
  Some metrics return both an amount and a count field, and may include other fields. For example, checkout conversion returns count, completed_count, and rate.

All responses include starts_at, ends_at, interval, and updated_at at the top level.

Next steps

This change is available in version 1 of the Paddle API.

These are new endpoints. There are no breaking changes to existing integrations. Existing API keys don't inherit the new metrics.read permission, so you'll need to update them to include it.

To get started, make sure the API key you're using has the metrics.read permission, then call any of the /metrics endpoints with a from and to date range.