POST
/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.
Requires transaction.read
permission.
Request body
No location information
Preview a transaction without using any address information.
customer_idstring | null
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$currency_codestring | null
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
discount_idstring | null
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$discountobject | null
Represents a discount entity for a custom, non-catalog discount.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
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.recurboolean
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false). If omitted, defaults to false.maximum_recurring_intervalsinteger | 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.
Min: 1
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
restrict_toarray | 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.Items: unique
ignore_trialsboolean
Default:
falseWhether 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.
itemsarrayrequired
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.
Catalog item
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
price_idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhPaddle ID of an existing catalog price to preview charging for, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$Non-catalog price for an existing product
Add a non-catalog price for an existing product in your catalog to a transaction. In this case, the product you're billing for is a catalog product, but you charge a specific price for it.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product_id to relate this non-catalog price to an existing catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$Non-catalog price and product
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product object to create a non-catalog product for this non-catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
productobjectrequired
Product object for a non-catalog item to charge for.
namestringrequired
Name of this product.
Length: 1–200
descriptionstring | null
Short description for this product.
Max length: 2048
tax_categorystringrequired
Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.
Values
digital-goodsNon-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.ebooksDigital books and educational material which is sold with permanent rights for use by the customer.implementation-servicesRemote configuration, set-up, and integrating software on behalf of a customer.professional-servicesServices that involve the application of your expertise and specialized knowledge of a software product.saasProducts that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values− Hide values
software-programming-servicesstandardSoftware products that are pre-written and can be downloaded and installed onto a local device.training-servicesTraining and education services related to software products.website-hostingCloud storage service for personal or corporate information, assets, or intellectual property.
image_url
Image for this product. Included in the checkout and on some customer documents.
Image Url
A URL to an image.
null
Empty String
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
Country and ZIP/postal code
Paddle uses the country and ZIP code (where supplied) to calculate totals.
customer_idstring | null
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$currency_codestring | null
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
discount_idstring | null
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$discountobject | null
Represents a discount entity for a custom, non-catalog discount.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
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.recurboolean
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false). If omitted, defaults to false.maximum_recurring_intervalsinteger | 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.
Min: 1
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
restrict_toarray | 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.Items: unique
ignore_trialsboolean
Default:
falseWhether 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.
itemsarrayrequired
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.
Catalog item
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
price_idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhPaddle ID of an existing catalog price to preview charging for, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$Non-catalog price for an existing product
Add a non-catalog price for an existing product in your catalog to a transaction. In this case, the product you're billing for is a catalog product, but you charge a specific price for it.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product_id to relate this non-catalog price to an existing catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$Non-catalog price and product
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product object to create a non-catalog product for this non-catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
productobjectrequired
Product object for a non-catalog item to charge for.
namestringrequired
Name of this product.
Length: 1–200
descriptionstring | null
Short description for this product.
Max length: 2048
tax_categorystringrequired
Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.
Values
digital-goodsNon-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.ebooksDigital books and educational material which is sold with permanent rights for use by the customer.implementation-servicesRemote configuration, set-up, and integrating software on behalf of a customer.professional-servicesServices that involve the application of your expertise and specialized knowledge of a software product.saasProducts that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values− Hide values
software-programming-servicesstandardSoftware products that are pre-written and can be downloaded and installed onto a local device.training-servicesTraining and education services related to software products.website-hostingCloud storage service for personal or corporate information, assets, or intellectual property.
image_url
Image for this product. Included in the checkout and on some customer documents.
Image Url
A URL to an image.
null
Empty String
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
addressobjectrequired
Address for this transaction preview.
postal_codestring | null
Example:
11105-1803ZIP or postal code of this address. Include for more accurate tax calculations.
Max length: 200
country_codestringrequired
Supported two-letter ISO 3166-1 alpha-2 country code for this address.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÅland IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PríncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
IP address
Paddle fetches location using the IP address to calculate totals.
customer_idstring | null
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$currency_codestring | null
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
discount_idstring | null
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$discountobject | null
Represents a discount entity for a custom, non-catalog discount.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
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.recurboolean
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false). If omitted, defaults to false.maximum_recurring_intervalsinteger | 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.
Min: 1
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
restrict_toarray | 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.Items: unique
ignore_trialsboolean
Default:
falseWhether 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.
itemsarrayrequired
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.
Catalog item
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
price_idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhPaddle ID of an existing catalog price to preview charging for, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$Non-catalog price for an existing product
Add a non-catalog price for an existing product in your catalog to a transaction. In this case, the product you're billing for is a catalog product, but you charge a specific price for it.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product_id to relate this non-catalog price to an existing catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$Non-catalog price and product
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product object to create a non-catalog product for this non-catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
productobjectrequired
Product object for a non-catalog item to charge for.
namestringrequired
Name of this product.
Length: 1–200
descriptionstring | null
Short description for this product.
Max length: 2048
tax_categorystringrequired
Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.
Values
digital-goodsNon-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.ebooksDigital books and educational material which is sold with permanent rights for use by the customer.implementation-servicesRemote configuration, set-up, and integrating software on behalf of a customer.professional-servicesServices that involve the application of your expertise and specialized knowledge of a software product.saasProducts that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values− Hide values
software-programming-servicesstandardSoftware products that are pre-written and can be downloaded and installed onto a local device.training-servicesTraining and education services related to software products.website-hostingCloud storage service for personal or corporate information, assets, or intellectual property.
image_url
Image for this product. Included in the checkout and on some customer documents.
Image Url
A URL to an image.
null
Empty String
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
customer_ip_addressstringrequired
IP address for this transaction preview.
Existing customer Paddle IDs
Paddle uses existing customer data to calculate totals. Typically used for logged-in customers.
currency_codestring | null
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
discount_idstring | null
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$discountobject | null
Represents a discount entity for a custom, non-catalog discount.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
typestringrequired
Type of discount. Determines how this discount impacts the checkout or transaction total.
Values
flatDiscounts a checkout or transaction by a flat amount, for example -$100. Requirescurrency_code.flat_per_seatDiscounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requirescurrency_code.percentageDiscounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
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.recurboolean
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false). If omitted, defaults to false.maximum_recurring_intervalsinteger | 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.
Min: 1
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
restrict_toarray | 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.Items: unique
ignore_trialsboolean
Default:
falseWhether 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.
itemsarrayrequired
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.
Catalog item
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
price_idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhPaddle ID of an existing catalog price to preview charging for, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$Non-catalog price for an existing product
Add a non-catalog price for an existing product in your catalog to a transaction. In this case, the product you're billing for is a catalog product, but you charge a specific price for it.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product_id to relate this non-catalog price to an existing catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$Non-catalog price and product
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.
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsboolean
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
priceobjectrequired
Price object for a non-catalog item to preview charging for. Include a
product object to create a non-catalog product for this non-catalog price.descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
namestring | null
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | null
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | null
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestring
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarray
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobject
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns. If omitted, defaults to 1-100.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
productobjectrequired
Product object for a non-catalog item to charge for.
namestringrequired
Name of this product.
Length: 1–200
descriptionstring | null
Short description for this product.
Max length: 2048
tax_categorystringrequired
Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.
Values
digital-goodsNon-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.ebooksDigital books and educational material which is sold with permanent rights for use by the customer.implementation-servicesRemote configuration, set-up, and integrating software on behalf of a customer.professional-servicesServices that involve the application of your expertise and specialized knowledge of a software product.saasProducts that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values− Hide values
software-programming-servicesstandardSoftware products that are pre-written and can be downloaded and installed onto a local device.training-servicesTraining and education services related to software products.website-hostingCloud storage service for personal or corporate information, assets, or intellectual property.
image_url
Image for this product. Included in the checkout and on some customer documents.
Image Url
A URL to an image.
null
Empty String
custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID of the customer that this transaction preview is for, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$address_idstringrequired
Example:
add_01gm302t81w94gyjpjpqypkzkfPaddle ID of the address that this transaction preview is for, prefixed with
add_. Requires customer_id.Pattern:
^add_[a-z\d]{26}$business_idstring | null
Example:
biz_01grrebrzaee2qj2fqqhmcyzajUnique Paddle ID for this business entity, prefixed with
biz_.Pattern:
^biz_[a-z\d]{26}$Response (200)
dataobjectrequired
Represents a transaction entity when previewing transactions.
customer_idstring | nullrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$address_idstring | nullrequired
Example:
add_01gm302t81w94gyjpjpqypkzkfUnique Paddle ID for this address entity, prefixed with
add_.Pattern:
^add_[a-z\d]{26}$business_idstring | nullrequired
Example:
biz_01grrebrzaee2qj2fqqhmcyzajUnique Paddle ID for this business entity, prefixed with
biz_.Pattern:
^biz_[a-z\d]{26}$currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
discount_idstring | nullrequired
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$customer_ip_addressstring | nullrequired
IP address for this transaction preview. Send one of
address_id, customer_ip_address, or the address object when previewing.addressobject | nullrequired
Represents an address entity when previewing addresses.
postal_codestring | nullrequired
Example:
11105-1803ZIP or postal code of this address. Include for more accurate tax calculations.
Max length: 200
country_codestringrequired
Supported two-letter ISO 3166-1 alpha-2 country code for this address.
Values
ADAndorraAEUnited Arab EmiratesAGAntigua and BarbudaAIAnguillaALAlbania
+ Show all values− Hide values
AMArmeniaAOAngolaARArgentinaASAmerican SamoaATAustriaAUAustraliaAWArubaAXÅland IslandsAZAzerbaijanBABosnia and HerzegovinaBBBarbadosBDBangladeshBEBelgiumBFBurkina FasoBGBulgariaBHBahrainBIBurundiBJBeninBLSaint BarthélemyBMBermudaBNBruneiBOBoliviaBQCaribbean Netherlands (Bonaire, Sint Eustatius, and Saba)BRBrazilBSBahamasBTBhutanBVBouvet IslandBWBotswanaBZBelizeCACanadaCCCocos IslandsCGRepublic of CongoCHSwitzerlandCICôte d'Ivoire (Ivory Coast)CKCook IslandsCLChileCMCameroonCNChinaCOColombiaCRCosta RicaCVCape VerdeCWCuraçaoCXChristmas IslandCYCyprusCZCzechia (Czech Republic)DEGermanyDJDjiboutiDKDenmarkDMDominicaDODominican RepublicDZAlgeriaECEcuadorEEEstoniaEGEgyptEHWestern SaharaEREritreaESSpainETEthiopiaFIFinlandFJFijiFKFalkland IslandsFMMicronesiaFOFaroe IslandsFRFranceGAGabonGBUnited KingdomGDGrenadaGEGeorgiaGFFrench GuianaGGGuernseyGHGhanaGIGibraltarGLGreenlandGMGambiaGNGuineaGPGuadeloupeGQEquatorial GuineaGRGreeceGSSouth Georgia and the South Sandwich IslandsGTGuatemalaGUGuamGWGuinea-BissauGYGuyanaHKHong KongHMHeard Island and McDonald IslandsHNHondurasHRCroatiaHUHungaryIDIndonesiaIEIrelandILIsraelIMIsle of ManINIndiaIOBritish Indian Ocean TerritoryIQIraqISIcelandITItalyJEJerseyJMJamaicaJOJordanJPJapanKEKenyaKGKyrgyzstanKHCambodiaKIKiribatiKMComorosKNSaint Kitts and NevisKRSouth KoreaKWKuwaitKYCayman IslandsKZKazakhstanLALao People's Democratic Republic (Laos)LBLebanonLCSaint LuciaLILiechtensteinLKSri LankaLRLiberiaLSLesothoLTLithuaniaLULuxembourgLVLatviaMAMoroccoMCMonacoMDMoldovaMEMontenegroMFSaint MartinMGMadagascarMHMarshall IslandsMKMacedoniaMNMongoliaMOMacaoMPNorthern Mariana IslandsMQMartiniqueMRMauritaniaMSMontserratMTMaltaMUMauritiusMVMaldivesMWMalawiMXMexicoMYMalaysiaMZMozambiqueNANamibiaNCNew CaledoniaNENigerNFNorfolk IslandNGNigeriaNLNetherlandsNONorwayNPNepalNRNauruNUNiueNZNew ZealandOMOmanPAPanamaPEPeruPFFrench PolynesiaPGPapua New GuineaPHPhilippinesPKPakistanPLPolandPMSaint Pierre and MiquelonPNPitcairnPRPuerto RicoPSPalestinian territoriesPTPortugalPWPalauPYParaguayQAQatarREReunionRORomaniaRSRepublic of SerbiaRWRwandaSASaudi ArabiaSBSolomon IslandsSCSeychellesSESwedenSGSingaporeSHSaint HelenaSISloveniaSJSvalbard and Jan MayenSKSlovakiaSLSierra LeoneSMSan MarinoSNSenegalSRSurinameSTSão Tomé and PríncipeSVEl SalvadorSXSint MaartenSZSwazilandTCTurks and Caicos IslandsTDChadTFFrench Southern and Antarctic LandsTGTogoTHThailandTJTajikistanTKTokelauTLTimor-LesteTMTurkmenistanTNTunisiaTOTongaTRTurkeyTTTrinidad and TobagoTVTuvaluTWTaiwanTZTanzaniaUAUkraineUGUgandaUMUnited States Minor Outlying IslandsUSUnited StatesUYUruguayUZUzbekistanVAHoly See (Vatican City)VCSaint Vincent and the GrenadinesVGBritish Virgin IslandsVIU.S. Virgin IslandsVNVietnamVUVanuatuWFWallis and FutunaWSSamoaXKKosovoYTMayotteZASouth AfricaZMZambia
ignore_trialsbooleanrequired
Default:
falseWhether 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.
itemsarrayrequired
List of items to preview transaction calculations for.
Items: 1–100
quantityintegerrequired
Quantity of this item on the transaction.
include_in_totalsbooleanrequired
Default:
trueWhether this item should be included in totals for this transaction preview. Typically used to exclude one-time charges from calculations.
prorationobject | nullrequired
How proration was calculated for this item. Populated when a transaction is created from a subscription change, where
proration_billing_mode was prorated_immediately or prorated_next_billing_period. Set automatically by Paddle.ratestringrequired
Rate used to calculate proration.
billing_periodobjectrequired
Billing period that proration is based on.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
priceobjectrequired
Represents a price preview entity.
idstring | nullrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$product_idstring | nullrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzUnique Paddle ID for this product, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$descriptionstringrequired
Internal description for this price, not shown to customers. Typically notes for your team.
Length: 2–500
typestringrequired
Default:
standardType of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
customNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
namestring | nullrequired
Name of this price, shown to customers at checkout and on invoices. Typically describes how often the related product bills.
Length: 1–150
billing_cycleobject | nullrequired
How often this price should be charged.
null if price is non-recurring (one-time).intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
trial_periodobject | nullrequired
Trial period for the product related to this price. The billing cycle begins once the trial period is over.
null for no trial period. Requires billing_cycle.intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
tax_modestringrequired
Default:
account_settingHow tax is calculated for this price.
Values
account_settingPrices use the setting from your account.externalPrices are exclusive of tax.internalPrices are inclusive of tax.locationPrices are inclusive or exclusive of tax, depending on the country of the transaction.
unit_priceobjectrequired
Base price. This price applies to all customers, except for customers located in countries where you have
unit_price_overrides.amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
unit_price_overridesarrayrequired
List of unit price overrides. Use to override the base price with a custom price and currency for a country or group of countries.
Items: max 250
country_codesarrayrequired
Supported two-letter ISO 3166-1 alpha-2 country code. Customers located in the listed countries are charged the override price.
Items: min 1, unique
string
Two-letter ISO 3166-1 alpha-2 representation of a supported country.
unit_priceobjectrequired
Override price. This price applies to customers located in the countries for this unit price override.
amountstringrequired
Amount in the lowest denomination for the currency, e.g. 10 USD = 1000 (cents). Although represented as a string, this value must be a valid integer.
currency_codestringrequired
Supported three-letter ISO 4217 currency code.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
quantityobjectrequired
Example:
{"minimum":1,"maximum":100}Limits on how many times the related product can be purchased at this price. Useful for discount campaigns.
minimumintegerrequired
Default:
1Example:
1Minimum quantity of the product related to this price that can be bought. Required if
maximum set.Range: 1–999999999
maximumintegerrequired
Default:
100Example:
100Maximum quantity of the product related to this price that can be bought. Required if
minimum set. Must be greater than or equal to the minimum value.Range: 1–999999999
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
detailsobjectrequired
Calculated totals for a transaction preview, including discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction preview.
tax_rates_usedarrayrequired
List of tax rates applied to this transaction preview.
tax_ratestringrequired
Example:
0.2Rate used to calculate tax for this transaction preview.
totalsobjectrequired
Calculated totals for the tax applied to this transaction preview.
subtotalstringrequired
Example:
15000Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example:
0Total discount as a result of any discounts applied.
Except for percentage discounts, Paddle applies tax to discounts based on the line item price.tax_mode. If price.tax_mode for a line item is internal, Paddle removes tax from the discount applied.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after discount and tax.
totalsobjectrequired
Breakdown of the total for a transaction preview.
fee and earnings always return null for transaction previews.subtotalstringrequired
Example:
15000Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example:
0Total discount as a result of any discounts applied.
Except for percentage discounts, Paddle applies tax to discounts based on the line item price.tax_mode. If price.tax_mode for a line item is internal, Paddle removes tax from the discount applied.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after discount and tax.
creditstringrequired
Example:
0Total credit applied to this transaction. This includes credits applied using a customer's credit balance and adjustments to a
billed transaction.credit_to_balancestringrequired
Example:
0Additional credit generated from negative
details.line_items. This credit is added to the customer balance.balancestringrequired
Example:
16500Total due on a transaction after credits and any payments.
grand_totalstringrequired
Example:
16500Total due on a transaction after credits but before any payments.
grand_total_taxstringrequired
Example:
83Net tax amount included in
grand_total. Equals the full tax amount unless credits are applied, in which case this value is proportionally reduced.feestring | nullrequired
Example:
825Total fee taken by Paddle for this transaction.
null until the transaction is completed and the fee is processed.earningsstring | nullrequired
Example:
15675Total earnings for this transaction. This is the total minus the Paddle fee.
null until the transaction is completed and the fee is processed.currency_codestringrequired
Three-letter ISO 4217 currency code of the currency used for this transaction.
Values
USDUnited States DollarEUREuroGBPPound SterlingJPYJapanese YenAUDAustralian Dollar
+ Show all values− Hide values
CADCanadian DollarCHFSwiss FrancHKDHong Kong DollarSGDSingapore DollarSEKSwedish KronaARSArgentine PesoBRLBrazilian RealCLPChilean PesoCNYChinese YuanCOPColombian PesoCZKCzech KorunaDKKDanish KroneHUFHungarian ForintILSIsraeli ShekelINRIndian RupeeKRWSouth Korean WonMXNMexican PesoNOKNorwegian KroneNZDNew Zealand DollarPENPeruvian SolPLNPolish ZlotyRUBRussian RubleTHBThai BahtTRYTurkish LiraTWDNew Taiwan DollarUAHUkrainian HryvniaVNDVietnamese DongZARSouth African Rand
line_itemsarrayrequired
Information about line items for this transaction preview. Different from transaction preview
items as they include totals calculated by Paddle. Considered the source of truth for line item totals.price_idstring | nullrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$quantityintegerrequired
Quantity of this transaction line item.
tax_ratestringrequired
Example:
0.2Rate used to calculate tax for this transaction line item.
unit_totalsobjectrequired
Breakdown of the charge for one unit in the lowest denomination of a currency (e.g. cents for USD).
subtotalstringrequired
Example:
15000Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example:
0Total discount as a result of any discounts applied.
Except for percentage discounts, Paddle applies tax to discounts based on the line item price.tax_mode. If price.tax_mode for a line item is internal, Paddle removes tax from the discount applied.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after discount and tax.
totalsobjectrequired
Breakdown of a charge in the lowest denomination of a currency (e.g. cents for USD).
subtotalstringrequired
Example:
15000Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example:
0Total discount as a result of any discounts applied.
Except for percentage discounts, Paddle applies tax to discounts based on the line item price.tax_mode. If price.tax_mode for a line item is internal, Paddle removes tax from the discount applied.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after discount and tax.
productobjectrequired
Related product entity for this transaction line item price.
idstring | nullrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzUnique Paddle ID for this product, prefixed with
pro_.Pattern:
^pro_[a-z\d]{26}$namestringrequired
Name of this product.
Length: 1–200
descriptionstring | nullrequired
Short description for this product.
Max length: 2048
typestringrequired
Default:
standardType of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
customNon-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.standardStandard item. Can be considered part of your catalog and reused across transactions and subscriptions easily.
tax_categorystringrequired
Tax category for this product. Used for charging the correct rate of tax. Selected tax category must be enabled on your Paddle account.
Values
digital-goodsNon-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.ebooksDigital books and educational material which is sold with permanent rights for use by the customer.implementation-servicesRemote configuration, set-up, and integrating software on behalf of a customer.professional-servicesServices that involve the application of your expertise and specialized knowledge of a software product.saasProducts that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values− Hide values
software-programming-servicesstandardSoftware products that are pre-written and can be downloaded and installed onto a local device.training-servicesTraining and education services related to software products.website-hostingCloud storage service for personal or corporate information, assets, or intellectual property.
image_urlrequired
Image for this product. Included in the checkout and on some customer documents.
Image Url
A URL to an image.
null
Empty String
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
statusstringrequired
Default:
activeWhether this entity can be used in Paddle.
Values
activeEntity is active and can be used.archivedEntity is archived, so can't be used.
import_metaobject | nullrequired
Import information for this entity.
null if this entity is not imported.external_idstring | null
Example:
9b95b0b8-e10f-441a-862e-1936a6d818abReference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example:
paddle_classicName of the platform or provider where this entity was imported from.
Length: 1–200
created_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example:
2024-10-13T07:20:50.52ZRFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
prorationobject | nullrequired
How proration was calculated for this item. Populated when a transaction is created from a subscription change, where
proration_billing_mode was prorated_immediately or prorated_next_billing_period. Set automatically by Paddle.ratestringrequired
Rate used to calculate proration.
billing_periodobjectrequired
Billing period that proration is based on.
starts_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string of when this period ends.
available_payment_methodsarrayrequired
List of available payment methods for Paddle Checkout given the price and location information passed.
Values
alipayAlipay, popular in China.apple_payApple Pay on a supported Apple device.bancontactBancontact, popular in Belgium.blikBLIK, a popular payment method in Poland.cardCredit or debit card.
+ Show all values− Hide values
google_payGoogle Pay on a supported Android device, Chromebook, or Google Chrome browser.idealiDEAL, popular in the Netherlands.kakao_payKakao Pay, a popular payment method in South Korea.korea_localKorean payment methods, which includes over 20 payment options for the Korean market.naver_payNaver Pay, a popular payment method in South Korea.paycoPayco, a popular payment method in South Korea.samsung_paySamsung Pay, a popular payment method in South Korea.south_korea_local_cardKorean local credit or debit card.mb_wayMB WAY, a popular payment method in Portugal.paypalPayPal.pixPix, popular in Brazil.upiUnified Payments Interface (UPI), popular in India.wechat_payWeChat Pay, a popular payment method in China.
metaobjectrequired
Information about this response.
request_idstringrequired
Example:
b15ec92e-8688-40d4-a04d-f44cbec93355Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
{ "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"}{ "data": { "customer_id": null, "address_id": null, "business_id": null, "currency_code": "USD", "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3", "address": { "postal_code": "", "country_code": "US" }, "customer_ip_address": null, "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", "import_meta": null }, "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", "import_meta": null }, "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", "import_meta": null }, "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", "grand_total_tax": "0", "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", "import_meta": null }, "tax_rate": "0", "unit_totals": { "subtotal": "3000", "tax": "0", "discount": "300", "total": "2700" }, "proration": null }, { "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", "import_meta": null }, "tax_rate": "0", "unit_totals": { "subtotal": "10000", "tax": "0", "discount": "1000", "total": "9000" }, "proration": null }, { "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", "import_meta": null }, "tax_rate": "0", "unit_totals": { "subtotal": "19900", "tax": "0", "discount": "1990", "total": "17910" }, "proration": null } ] }, "ignore_trials": false, "available_payment_methods": [ "apple_pay", "card", "paypal", "google_pay" ] }, "meta": { "request_id": "eb3d6481-6799-4e30-8676-0dc96a356182" }}