How to get KPIs and metrics from the Paddle API

Paddle is a merchant of record payment platform. They let you collect payments for your recurring and non recurring digital products and subscriptions. They also handle worldwide sales tax remittance, first level billing support and chargebacks for you . They offer a mondern REST Api to access almost all information for your account. You can find their documentation here: Paddle Developer.

Contents

• Authentication
• Endpoints
• How to get revenue metrics from Paddle
• How to get non-recurring revenue metrics from Paddle
• How to get entity metrics from Paddle like Number of Customers

Authentication

For authentication you need a Paddle API Key avialable from the Paddle dashboard under the Developer Tools > Authentication.

Endpoints

Paddle provides two endpoints that are useful for metrics dashboards.

For payment related metrics such as revenue you use the transactions endpoint at:

https://api.paddle.com/transactions

For entity related metrics such as customer or subscriber counts you will use the events endpoint at:

https://api.paddle.com/events

How to get revenue metrics from Paddle

This endpoint gives you all transactions on your account (Documentation).

For these requests the entity_id parameter is the id of the site you want to get data for. You can get this from your Sites page in Fathom.

https://api.paddle.com/transactions
  // See options below
  ?status=completed
  &billed_at[GTE]=2024-01-01T00:00:00.000000Z
  &billed_at[LT]=2024-02-01T00:00:00.000000Z

Options for aggregates parameter:

• status: Use value completed to get only actual payments that have been processed
• billed_at with [GTE] or [LT]: To filter for a specific date period specify the GTE (Greated than or equal) or LT (Lower than) parameters in RFC 3339 format.

Subscription Payment Results

The endpoint will return the following data (showing only properties that are relevant for the metrics calculation):

{
  "data": [
    {
      "id": "txn_...",
      "status": "completed",
      "billed_at": "2024-04-12T10:33:52.610609Z",
      "items": [
        {
          "price": {
            "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
            "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "billing_cycle": {
              "interval": "month",
              "frequency": 1
            },
          },
          "quantity": 10
        },
      
      ],
      "details": {
        "payout_totals": {
          "total": "123",
          "earnings": "123",
          "currency_code": "USD"
        },
        "line_items": [
          {
            "id": "txnitm_01hv8xxw6qxaypzmf81xqgcba9",
            "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
            "quantity": 10,
            "totals": {
              "subtotal": "24000",
              "tax": "4800",
              "discount": "0",
              "total": "28800"
            },
          },
        ]
      },
    },
  ],
  "meta": {
    "pagination": {
      "per_page": 30,
      "next": "https://api.paddle.com/transactions?after=txn_01hv8kxg3hxyxs9t471ms9kfsz",
      "has_more": false,
      "estimated_total": 6
    }
  }
}

Each request will contain at most 50 items and you can retrieve further pages by using the meta.pagination.next url.

Calculating recurring revenue metrics from the Paddle API

The endpoint return all transactions for the date period including one-off products and one-off charges on subscriptions. In order to calculate the recurring revenue portion of a transaction you must do the following:

1. Determine which which price ids represent recurring items by checking the items property. Those with a billing_cycle property set to null are non recurring and can be ignored.
2. Calculate the proportion of the line items transaction value that is monthly. If the billing_cycle is set to annual, any transaction value must be divided by 12 to get the monthly portion.
3. Sum the totals.total value from each details.line_item that represents a recurring price (first dividing by the factor calculated in 2) to get the total amount of recurring revenue in this transaction. This value is in the buyer’s currency. Divide it by the total transaction value (sum up totals.total value from all details.line_item this time) to get a factor of the transaction representing recurring revenue.
4. Apply this factor to the details.payout_totals.earnings value to get the recurring revenue portion of this transaction in your payout currency.

Repeat for each transaction and aggregate by month to get a monthly recurring revenue number.

How to get non-recurring revenue metrics from Paddle

Follow the instructions for recurring revenue metric calculation but instead check that the line_items billing_cycle property is set to null.

How to get entity metrics from Paddle like Number of Customers

There is no way currently to ask the API for entities like subscribers or customers created within a certain period. But the events endpoint let you request all events. Events represent a certain entity event and have a event_type property to describe the event, e.g. customer.created.

Unfortunately you can only request all events (and page through them) but not events within a certain period by issuing a GET request to:

https://api.paddle.com/events

Events Results

The endpoint will return the following data (showing only properties that are relevant for the metrics calculation):

{
  "data": [
    {
      "event_id": "evt_01hv976dvatn4n7hyezq5jatef",
      "event_type": "customer.created",
      "occurred_at": "2024-04-12T13:15:49.994206Z",
    },
    ...
  ],
  "meta": {
    "pagination": {
      "per_page": 50,
      "estimated_total": 12,
      "next": "https://api.paddle.com/events?after=evt_...",
      "has_more": false
    },
    "request_id": "249029c3-2342-4c8b-a946-75ad1052a1bd"
  }
}

Each request will contain at most 50 items and you can retrieve further pages by using the meta.pagination.next url.

Calculating entity metrics from the Paddle API

You can filter the events in the data array by event_type and occurred_at to count the different entity events and aggregate them for a specific date period.