Get metrics data for your account using the API
Build dashboards and analytics pipelines with seven new metrics operations that return timeseries data about your Paddle account.
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
amountfield, 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
countfield.Mixed
Some metrics return both an
amountand acountfield, and may include other fields. For example, checkout conversion returnscount,completed_count, andrate.
All responses include starts_at, ends_at, interval, and updated_at at the top level.
Summary of changes
Operations
This is a summary of the new API operations in the metrics category:
| Operation | Method | Details |
|---|---|---|
| Get monthly recurring revenue | GET | /metrics/monthly-recurring-revenue |
| Daily MRR across active subscriptions | ||
| Get MRR change | GET | /metrics/monthly-recurring-revenue-change |
| Daily net change in MRR | ||
| Get active subscribers | GET | /metrics/active-subscribers |
| Daily count of active subscribers | ||
| Get revenue | GET | /metrics/revenue |
| Daily revenue collected and transaction count | ||
| Get refunds | GET | /metrics/refunds |
| Daily refunded amount | ||
| Get chargebacks | GET | /metrics/chargebacks |
| Daily chargeback count | ||
| Get checkout conversion | GET | /metrics/checkout-conversion |
| Daily checkout sessions, completions, and conversion rate |
Permissions
This is a summary of the new permissions required:
| Permission | Description |
|---|---|
metrics.read | Read metrics data. Required for all /metrics endpoints. |
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.