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 when previewing a transaction. You must provide this if you want Paddle to calculate tax or automatically localize prices. 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 don't create transactions, so no id is returned.

Request Body

Any of:

No location informationCountry and ZIP/postal codeIP addressExisting customer Paddle IDs

itemsarray[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.

One of:

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

price_idstringrequired

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

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.

customer_idstring or null

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

currency_codestring or null

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.

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