Preview a transaction

posthttps://api.paddle.com/transactions/preview

Previews a transaction without creating a transaction entity. Typically used for creating more advanced, dynamic pricing pages where users can build their own plans.

Consider using the preview prices operation for simpler pricing pages.

You can provide location information to preview a transaction. Paddle uses this to calculate tax. You can provide one of:

customer_ip_address: Paddle fetches location using the IP address to calculate totals.
address: Paddle uses the country and ZIP code (where supplied) to calculate totals.
customer_id, address_id, business_id: Paddle uses existing customer data to calculate totals. Typically used for logged-in customers.

When supplying items, you can exclude items from the total calculation using the include_in_totals boolean.

By default, recurring items with trials are considered to have a zero charge when previewing. Set ignore_trials to true to ignore trial periods against prices for transaction preview calculations.

If successful, your response includes the data you sent with a details object that includes totals for the supplied prices.

Transaction previews do not create transactions, so no id is returned.

Request Body

One of:

Country and ZIP/postal codeIP addressExisting customer Paddle IDs

addressobjectrequired

Address for this transaction preview.

postal_codestring or null

ZIP or postal code of this address. Include for more accurate tax calculations.

country_codestringrequired

Supported two-letter ISO 3166-1 alpha-2 country code for this address.

customer_idstring or null

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

currency_codestring

Supported three-letter ISO 4217 currency code.

discount_idstring or null

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

ignore_trialsboolean

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.

itemsarray[object]required

Add a non-catalog price for a non-catalog product in your catalog to a transaction. In this case, the product and price that you're billing for are specific to this transaction.

One of:

Catalog itemNon-catalog price for an existing productNon-catalog price and product

quantityintegerrequired

Quantity of this item on the transaction.

include_in_totalsboolean

Whether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.

price_idstringrequired

Paddle ID of an existing catalog price to preview charging for, prefixed with pri_.

Response

dataobject

Represents a transaction entity when previewing transactions.

customer_idstring or null

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

address_idstring or null

Paddle ID of the address that this transaction preview is for, prefixed with add_. Send one of address_id, customer_ip_address, or the address object when previewing.

business_idstring or null

Paddle ID of the business that this transaction preview is for, prefixed with biz_.

currency_codestring

Supported three-letter ISO 4217 currency code.

discount_idstring or null

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

customer_ip_addressstring or null

IP address for this transaction preview. Send one of address_id, customer_ip_address, or the address object when previewing.

addressobject or null

Address for this transaction preview. Send one of address_id, customer_ip_address, or the address object when previewing.

ignore_trialsboolean

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.

itemsarray[object]

List of items to preview transaction calculations for.

detailsobject

Calculated totals for a transaction preview, including discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction preview.

available_payment_methodsarray[string]

List of available payment methods for Paddle Checkout given the price and location information passed.

metaobject

Information about this response.

request_idstring

Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "items": [
3    {
4      "quantity": 20,
5      "price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke"
6    },
7    {
8      "quantity": 1,
9      "price_id": "pri_01h1vjfevh5etwq3rb416a23h2"
10    },
11    {
12      "quantity": 1,
13      "price_id": "pri_01gsz98e27ak2tyhexptwc58yk",
14      "include_in_totals": false
15    }
16  ],
17  "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3",
18  "address": {
19    "country_code": "US"
20  },

Response