Skip to main content
POST
/
transactions
/
preview
Preview a transaction
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {quantity: 20, price_id: 'pri_01gsz8x8sawmvhz1pv30nge1ke'},
      {quantity: 1, price_id: 'pri_01h1vjfevh5etwq3rb416a23h2'},
      {
        quantity: 1,
        price_id: 'pri_01gsz98e27ak2tyhexptwc58yk',
        include_in_totals: false
      }
    ],
    discount_id: 'dsc_01gtgztp8fpchantd5g1wrksa3',
    address: {country_code: 'US'},
    currency_code: 'USD'
  })
};

fetch('https://api.paddle.com/transactions/preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "data": {
    "customer_id": null,
    "address_id": null,
    "business_id": null,
    "currency_code": "USD",
    "address": {
      "postal_code": "",
      "country_code": "US"
    },
    "customer_ip_address": null,
    "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3",
    "items": [
      {
        "price": {
          "id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "description": "Monthly",
          "type": "standard",
          "name": "Monthly (per seat)",
          "product_id": "pro_01gsz4t5hdjse780zja8vvr7jg",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "3000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 999
          },
          "status": "active",
          "created_at": "2023-02-23T13:55:22.538367Z",
          "updated_at": "2024-04-11T13:54:52.254748Z"
        },
        "quantity": 20,
        "proration": null,
        "include_in_totals": true
      },
      {
        "price": {
          "id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "description": "Monthly",
          "type": "standard",
          "name": "Monthly (recurring addon)",
          "product_id": "pro_01h1vjes1y163xfj1rh1tkfb65",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "10000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "status": "active",
          "created_at": "2023-06-01T13:31:12.625056Z",
          "updated_at": "2024-04-09T07:23:00.907834Z"
        },
        "quantity": 1,
        "proration": null,
        "include_in_totals": true
      },
      {
        "price": {
          "id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "description": "One-time addon",
          "type": "standard",
          "name": "One-time addon",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "billing_cycle": null,
          "trial_period": null,
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "19900",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "status": "active",
          "created_at": "2023-02-23T14:01:28.391712Z",
          "updated_at": "2024-04-09T07:23:10.921392Z"
        },
        "quantity": 1,
        "proration": null,
        "include_in_totals": false
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0",
          "totals": {
            "subtotal": "70000",
            "discount": "7000",
            "tax": "0",
            "total": "63000"
          }
        }
      ],
      "totals": {
        "subtotal": "70000",
        "tax": "0",
        "discount": "7000",
        "total": "63000",
        "grand_total": "63000",
        "fee": null,
        "credit": "0",
        "credit_to_balance": "0",
        "balance": "63000",
        "earnings": null,
        "currency_code": "USD"
      },
      "line_items": [
        {
          "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke",
          "quantity": 20,
          "totals": {
            "subtotal": "60000",
            "tax": "0",
            "discount": "6000",
            "total": "54000"
          },
          "product": {
            "id": "pro_01gsz4t5hdjse780zja8vvr7jg",
            "name": "AeroEdit Pro",
            "description": "Designed for professional pilots, including all features plus in Basic plus compliance monitoring, route optimization, and third-party integrations.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/bT1XUOJAQhOUxGs83cbk_pro.png",
            "custom_data": {
              "features": {
                "aircraft_performance": true,
                "compliance_monitoring": true,
                "flight_log_management": true,
                "payment_by_invoice": false,
                "route_planning": true,
                "sso": false
              },
              "suggested_addons": [
                "pro_01h1vjes1y163xfj1rh1tkfb65",
                "pro_01gsz97mq9pa4fkyy0wqenepkz"
              ],
              "upgrade_description": "Move from Basic to Pro to take advantage of aircraft performance, advanced route planning, and compliance monitoring."
            },
            "status": "active",
            "created_at": "2023-02-23T12:43:46.605Z",
            "updated_at": "2024-04-05T15:53:44.687Z"
          },
          "tax_rate": "0",
          "unit_totals": {
            "subtotal": "3000",
            "tax": "0",
            "discount": "300",
            "total": "2700"
          }
        },
        {
          "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
          "quantity": 1,
          "totals": {
            "subtotal": "10000",
            "tax": "0",
            "discount": "1000",
            "total": "9000"
          },
          "product": {
            "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
            "name": "Analytics addon",
            "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
            "custom_data": null,
            "status": "active",
            "created_at": "2023-06-01T13:30:50.302Z",
            "updated_at": "2024-04-05T15:47:17.163Z"
          },
          "tax_rate": "0",
          "unit_totals": {
            "subtotal": "10000",
            "tax": "0",
            "discount": "1000",
            "total": "9000"
          }
        },
        {
          "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
          "quantity": 1,
          "totals": {
            "subtotal": "19900",
            "tax": "0",
            "discount": "1990",
            "total": "17910"
          },
          "product": {
            "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
            "name": "Custom domains",
            "description": "Make AeroEdit truly your own with custom domains. Custom domains reinforce your brand identity and make it easy for your team to access your account.",
            "type": "standard",
            "tax_category": "standard",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/XIG7UXoJQHmlIAiKcnkA_custom-domains.png",
            "custom_data": null,
            "status": "active",
            "created_at": "2023-02-23T14:01:02.441Z",
            "updated_at": "2024-04-05T15:43:28.971Z"
          },
          "tax_rate": "0",
          "unit_totals": {
            "subtotal": "19900",
            "tax": "0",
            "discount": "1990",
            "total": "17910"
          }
        }
      ]
    },
    "ignore_trials": false,
    "available_payment_methods": [
      "apple_pay",
      "card",
      "paypal",
      "google_pay"
    ]
  },
  "meta": {
    "request_id": "eb3d6481-6799-4e30-8676-0dc96a356182"
  }
}

Authorizations

​
Authorization
string
header
required

Requests are authenticated with API keys. Provide your API key as a Bearer token in the Authorization header.

API keys are assigned permissions, granting them access to entities and operations. Each endpoint may require one or more permissions, defined with the x-permissions extension. Values for include parameters may require specific permissions as defined in the x-enum-permissions extension. See all available permissions in the permission schema or documentation.

Get an API key and select the permissions you need from the Paddle dashboard under Paddle > Developer Tools > Authentication.

Body

application/json

Preview a transaction without using any address information.

​
items
(Catalog item · object | Non-catalog price for an existing product · object | Non-catalog price and product · object)[]
required

List of items to preview charging for. You can preview charging for items that you've added to your catalog by passing the Paddle ID of an existing price entity, or you can preview charging for non-catalog items by passing a price object.

Non-catalog items can be for existing products, or you can pass a product object as part of your price to preview charging for a non-catalog product.

Add a catalog item to a transaction. In this case, the product and price that you're billing for exist in your product catalog in Paddle.

​
customer_id
string | null

Paddle ID of the customer that this transaction preview is for, prefixed with ctm_.

Example:

"ctm_01grnn4zta5a1mf02jjze7y2ys"

​
currency_code
enum<string> | null

Supported three-letter ISO 4217 currency code.

Available options:
USD,
EUR,
GBP,
JPY,
AUD,
CAD,
CHF,
HKD,
SGD,
SEK,
ARS,
BRL,
CNY,
COP,
CZK,
DKK,
HUF,
ILS,
INR,
KRW,
MXN,
NOK,
NZD,
PLN,
RUB,
THB,
TRY,
TWD,
UAH,
VND,
ZAR
Required string length: 3
​
discount_id
string | null

Paddle ID of the discount applied to this transaction preview, prefixed with dsc_.

Example:

"dsc_01gv5kpg05xp104ek2fmgjwttf"

​
ignore_trials
boolean
default:false

Whether trials should be ignored for transaction preview calculations.

By default, recurring items with trials are considered to have a zero charge when previewing. Set to true to disable this.

Response

OK

​
data
TransactionPreview · object
required

Represents a transaction entity when previewing transactions.

​
meta
Meta · object
required

Information about this response.