Preview a transaction

Permission required

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 to apply to this transaction preview, prefixed with dsc_. Send one of discount_id or discount.

discountobject or null

Apply a non-catalog discount to a transaction. Send one of discount_id or discount.

amountstringrequired

Amount to discount by. For percentage discounts, must be an amount between 0.01 and 100. For flat and flat_per_seat discounts, amount in the lowest denomination for a currency.

descriptionstringrequired

Short description for this discount for your reference. Not shown to customers.

typestringrequired

Type of discount. Determines how this discount impacts the checkout or transaction total.

recurboolean

Whether this discount applies for multiple subscription billing periods (true) or not (false). If omitted, defaults to false.

maximum_recurring_intervalsinteger or null

Number of subscription billing periods that this discount recurs for. Requires recur. null if this discount recurs forever.

Subscription renewals, midcycle changes, and one-time charges billed to a subscription aren't considered a redemption. times_used is not incremented in these cases.

custom_dataobject or null

Your own structured key-value data.

restrict_toarray[string] or null

Product or price IDs that this discount is for. When including a product ID, all prices for that product can be discounted. null if this discount applies to all products and prices.

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