How to get KPIs and metrics from the Paddle Classic API

Paddle Classic was the old version of the payment platform Paddle that. As a merchant of record they let you collect payments for your products and handle sales tax remittance for you worldwide . You cannot create new accounts for Paddle Classic (only for the new Paddle Billing), but you can find their documentation here: Paddle Classic Documentation.

Contents

• Authentication
• Endpoints
• How to get recurring revenue metrics from Paddle Classic
• How to get non-recurring revenue metrics from Paddle Classic

Authentication

For authentication you need a vendor id and vendor auth code available from the Paddle Classic dashboard under the Developer Tools > Authentication.

The Paddle Classic API only accepts HTTP POST requests with a JSON payload. Both authentication values must be passed as vendor_id and vendor_auth_code respectively alongside any additional query parameters.

{
  "vendor_id": "12345",
  "vendor_auth_code": "abcdef"
}

Endpoints

Paddle Classic provides two endpoints that provide transaction information to calculate revenue metrics.

In order to calculate recurring revenue across all products it’s easiest to use the subscription payments endpoint and only take those payments into account that have the one off property set to false.

In order to calculate total revenue you must call the transactions endpoint for every product and subscription plan. This will give you all payments for your account and you can sum the value provided.

In order to calculate non recurring revenue you must call the transactions endpoint for every product and then for every subscription plan. For the subscription payments take only payments with the one-off property set to true into account.

How to get recurring revenue metrics from Paddle Classic

This endpoint gives you all payments across all subscriptions (including one off payments as part of a subscription) (Documentation).

To make a request POST a JSON request to https://vendors.paddle.com/api/2.0/subscription/payments.

{
  // authentication, see above
  "vendor_id": "12345",
  "vendor_auth_code": "abcdef",
  // query
  "is_paid": 1,
  "is_one_off_charge": 0,
  "from": "2024-01-01",
  "to": "2025-01-01"
}

Options for aggregates parameter:

• is_paid: 1 for completed payments, 0 for not yet completed.
• is_one_off_charge: Subscriptions may still contain non-recurring items, but for recurring payments only set this to 1.
• from and to: Date period for the query in ISO date format. Note Paddle Classic only let’s you filter by date. The to date is exclusive, so in the above query results until 2024-12-31 are returned.

Subscription Payment Results

The endpoint will return the following data:

{
  "success": true,
  "response": [
    {
      "id": 12345678,
      "subscription_id": 12345678,
      "amount": 42,
      "currency": "USD",
      "payout_date": "2024-08-18"
    }
  ]
}

Each request will contain at most 15 items and you can retrieve further pages by adding the page parameter to the query.

Calculating recurring revenue metrics

You can calculate the total revenue by

• retrieving the subscription payments for a given date period,
• then sum the values of the amount property,
• but note that you must convert the buyer’s currency to the same currency before calculating the total.

How to get non-recurring revenue metrics from Paddle Classic

This endpoint gives you all payments for a single product (one time product or subscription plan) (Documentation).

To make a request POST a JSON request to https://vendors.paddle.com/api/2.0/{entity}/{id}/transactions replacing entity with either product (for one-time products) or subscription (for subscriptions) and the corresponding id.

{
  // authentication, see above
  "vendor_id": "12345",
  "vendor_auth_code": "abcdef",
  // pagination
  "page": 1,
  // query
  "from": "2024-01-01",
  "to": "2025-01-01"
}

Options for aggregates parameter:

• is_paid: 1 for completed payments, 0 for not yet completed.
• is_one_off_charge: Subscriptions may still contain non-recurring items, but for recurring payments only set this to 1.
• from and to: Date period for the query in ISO date format. Note Paddle Classic only let’s you filter by date. The to date is exclusive, so in the above query results until 2024-12-31 are returned.

Transaction Payments Results

The endpoint will return the following data:

{
  "success": true,
  "response": [
    {
      "order_id": "1042907-384786",
      "amount": "5.00",
      "currency": "USD",
      "status": "completed",
      "created_at": "2017-01-22 00:38:43"
    },
    ...
  ]
}

Each request will contain at most 15 items and you can retrieve further pages by adding the page parameter to the query.

Calculating non-recurring revenue metrics

You can calculate the total revenue by

• first retrieving the payments for each product in your account,
• then using the sum of the amount property for a given date period using created_at,
• but note that you must convert the buyer’s currency to the same currency before calculating the total.