PATCH
/transactions/{transaction_id} Updates a transaction using its ID.
You can update transactions that are draft or ready. billed and completed transactions are considered records for tax and legal purposes, so they can't be changed. You can either:
- Create an adjustment to record a refund or credit for a transaction.
- Cancel a
billedtransaction by sending a PATCH request to setstatustocanceled.
The transaction status may only be set to billed or canceled. Other statuses are set automatically by Paddle. Set a manually-collected transaction to billed to mark it as finalized. This is essentially issuing an invoice. At this point, it becomes a legal record so you can't make changes to it. Paddle automatically assigns an invoice number, creates a related subscription, and sends it to your customer.
When making changes to items on a transaction, send the complete list of items that you'd like to be on a transaction — including existing items. For each item, send an object containing price_id and quantity. Paddle responds with the full price object for each item. See: Work with lists
If successful, your response includes a copy of the updated transaction entity.
Requires transaction.write
permission.
Path parameters
transaction_idstringrequired
Paddle ID of the transaction entity to work with.
Query parameters
includearray
Include related entities in the response. Use a comma-separated list to specify multiple entities.
Values
addressInclude an object for the address entity related to this transaction. Only included where anaddress_idis set against the transaction.adjustmentsInclude an array of adjustments related to this transaction. Only included where a transaction has adjustments.adjustments_totalsInclude an object that includes totals for all adjustments against this transaction.available_payment_methodsInclude an array of available payment methods for this transaction.businessInclude an object for the business entity related to this transaction. Only included where abusiness_idis set against the transaction.
+ Show all values− Hide values
customerInclude an object for the customer entity related to this transaction. Only included where acustomer_idis set against the transaction.discountInclude an object for the discount entity related to this transaction. Only included where adiscount_idis set against the transaction.
Request body
statusstring
Status of this transaction. You may set a transaction to billed or canceled. Billed transactions cannot be changed.
For manually-collected transactions, marking as billed is essentially issuing an invoice.
Values
draftTransaction is missing required fields. Typically the first stage of a checkout before customer details are captured.readyTransaction has all of the required fields to be marked asbilledorcompleted.billedTransaction has been updated tobilled. Billed transactions get an invoice number and are considered a legal record. They cannot be changed. Typically used as part of an invoice workflow.paidTransaction is fully paid, but has not yet been processed internally.completedTransaction is fully paid and processed.
+ Show all values− Hide values
canceledTransaction has been updated tocanceled. If an invoice, it's no longer due.past_dueTransaction is past due. Occurs for automatically-collected transactions when the related subscription is in dunning, and for manually-collected transactions when payment terms have elapsed.
customer_idstring | null
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$address_idstring | null
Example:
add_01gm302t81w94gyjpjpqypkzkfUnique Paddle ID for this address entity, prefixed with
add_.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}$custom_dataobject | null
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
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
originstring
Values
apiTransaction created via the Paddle API.subscription_chargeTransaction created automatically by Paddle as a result of a one-time charge for a subscription.subscription_payment_method_changeTransaction created automatically as part of updating a payment method. May be a zero value transaction.subscription_recurringTransaction created automatically by Paddle as a result of a subscription renewal.subscription_updateTransaction created automatically by Paddle as a result of an update to a subscription.
+ Show all values− Hide values
webTransaction created automatically by Paddle.js for a checkout.
collection_modestring
How payment is collected for this transaction.
automatic for checkout, manual for invoices.Values
automaticPayment is collected automatically using a checkout initially, then using a payment method on file.manualPayment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requiresbilling_details.
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
billing_detailsobject | null
Details for invoicing. Required if
collection_mode is manual.enable_checkoutboolean
Default:
falseWhether the related transaction may be paid using Paddle Checkout.
purchase_order_numberstring
Customer purchase order number. Appears on invoice documents.
Max length: 100
additional_informationstring | null
Notes or other information to include on this invoice. Appears on invoice documents.
Max length: 1500
payment_termsobject
How long a customer has to pay this invoice once issued.
intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
billing_periodobject | null
Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for.
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.
itemsarray
List of items on this transaction.
When making a request, each object must contain either a price_id or a price object, and a quantity.
Include a price_id to charge for an existing catalog item, or a price object to charge for a non-catalog item.
Items: 1–100
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.
Min: 1
price_idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhPaddle ID of an existing catalog price to add to this transaction, 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.
Min: 1
priceobjectrequired
Price object for a non-catalog item to charge 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.
Min: 1
priceobjectrequired
Price object for a non-catalog item to charge 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.
checkoutobject | null
Paddle Checkout details for this transaction. You may pass a URL when creating or updating an automatically-collected transaction, or when creating or updating a manually-collected transaction where
billing_details.enable_checkout is true.urlstring | null
Checkout URL to use for the payment link for this transaction. Pass the URL for an approved domain, or null to set to your default payment URL.
Paddle returns a unique payment link composed of the URL passed or your default payment URL + ?_ptxn= and the Paddle ID for this transaction.
Length: 1–2048
Response (200)
dataobjectrequired
Represents a transaction entity with included entities.
idstringrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cUnique Paddle ID for this transaction entity, prefixed with
txn_.Pattern:
^txn_[a-z\d]{26}$statusstringrequired
Status of this transaction. You may set a transaction to
billed or canceled, other statuses are set automatically by Paddle. Automatically-collected transactions may return completed if payment is captured successfully, or past_due if payment failed.Values
draftTransaction is missing required fields. Typically the first stage of a checkout before customer details are captured.readyTransaction has all of the required fields to be marked asbilledorcompleted.billedTransaction has been updated tobilled. Billed transactions get an invoice number and are considered a legal record. They cannot be changed. Typically used as part of an invoice workflow.paidTransaction is fully paid, but has not yet been processed internally.completedTransaction is fully paid and processed.
+ Show all values− Hide values
canceledTransaction has been updated tocanceled. If an invoice, it's no longer due.past_dueTransaction is past due. Occurs for automatically-collected transactions when the related subscription is in dunning, and for manually-collected transactions when payment terms have elapsed.
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}$custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
currency_codestringrequired
Supported three-letter ISO 4217 currency code. Must be
USD, EUR, or GBP if collection_mode is manual.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
originstringrequired
Describes how this transaction was created.
Values
apiTransaction created via the Paddle API.subscription_chargeTransaction created automatically by Paddle as a result of a one-time charge for a subscription.subscription_payment_method_changeTransaction created automatically as part of updating a payment method. May be a zero value transaction.subscription_recurringTransaction created automatically by Paddle as a result of a subscription renewal.subscription_updateTransaction created automatically by Paddle as a result of an update to a subscription.
+ Show all values− Hide values
webTransaction created automatically by Paddle.js for a checkout.
subscription_idstring | nullrequired
Example:
sub_01h04vsc0qhwtsbsxh3422wjs4Unique Paddle ID for this subscription entity, prefixed with
sub_.Pattern:
^sub_[a-z\d]{26}$invoice_idstring | nullrequireddeprecated
Example:
inv_01ghbk4xjn4qdsmstcwzgcgg35Paddle ID of the invoice that this transaction is related to, prefixed with
inv_. Used for compatibility with the Paddle Invoice API, which is now deprecated. This field is scheduled to be removed in the next version of the Paddle API.Pattern:
^inv_[a-z\d]{26}$invoice_numberstring | nullrequired
Example:
123-45678Document number that is automatically generated by Paddle.
collection_modestringrequired
Default:
automaticHow payment is collected for this transaction.
automatic for checkout, manual for invoices.Values
automaticPayment is collected automatically using a checkout initially, then using a payment method on file.manualPayment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requiresbilling_details.
discount_idstring | nullrequired
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$billing_detailsobject | nullrequired
Details for invoicing. Required if
collection_mode is manual.enable_checkoutbooleanrequired
Default:
falseWhether the related transaction may be paid using Paddle Checkout. If omitted when creating a transaction, defaults to
false.purchase_order_numberstringrequired
Customer purchase order number. Appears on invoice documents.
Max length: 100
additional_informationstring | nullrequired
Notes or other information to include on this invoice. Appears on invoice documents.
Max length: 1500
payment_termsobjectrequired
How long a customer has to pay this invoice once issued.
intervalstringrequired
Unit of time.
Values
dayweekmonthyear
frequencyintegerrequired
Amount of time.
Min: 1
billing_periodobject | nullrequired
Time period that this transaction is for. Set automatically by Paddle for subscription renewals to describe the period that charges are for.
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.
itemsarrayrequired
List of items on this transaction. For calculated totals, use
details.line_items.Items: 1–100
priceobjectrequired
Represents a price entity.
idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhUnique Paddle ID for this price, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$product_idstringrequired
Example:
pro_01gsz97mq9pa4fkyy0wqenepkzPaddle ID for the product that this price is for, 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
requires_payment_methodbooleanrequired
Default:
trueWhether this price requires a payment method (
true) or not (false) when trialing. If false, customers can sign up for subscription without entering their payment details, often referred to as a "cardless trial."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.
quantityintegerrequired
Quantity of this item on the transaction.
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.
detailsobjectrequired
Calculated totals for a transaction, including proration, discounts, tax, and currency conversion. Considered the source of truth for totals on a transaction.
tax_rates_usedarrayrequired
List of tax rates applied for this transaction.
tax_ratestringrequired
Example:
0.2Rate used to calculate tax for this transaction.
totalsobjectrequired
Calculated totals for the tax applied to this transaction.
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. These numbers can be negative when dealing with subscription updates that result in credit.
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
adjusted_totalsobjectrequired
Breakdown of the totals for a transaction after adjustments.
subtotalstringrequired
Example:
15000Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after tax.
grand_totalstringrequired
Example:
16500Total due 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.retained_feestringrequired
Example:
300Total Paddle fees retained for this adjustment.
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
payout_totalsobject | nullrequired
Breakdown of the payout total for a transaction.
null until the transaction is completed. Returned in your payout currency.subtotalstringrequired
Example:
15000Total before tax and fees.
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 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.feestringrequired
Example:
825Total fee taken by Paddle for this payout.
earningsstringrequired
Example:
15675Total earnings for this payout. This is the subtotal minus the Paddle fee.
currency_codestringrequired
Three-letter ISO 4217 currency code used for the payout for this transaction. If your primary currency has changed, this reflects the primary currency at the time the transaction was billed.
Values
AUDAustralian DollarCADCanadian DollarCHFSwiss FrancCNYChinese YuanCZKCzech Koruna
+ Show all values− Hide values
DKKDanish KroneEUREuroGBPPound SterlingHUFHungarian ForintPLNPolish ZlotySEKSwedish KronaUSDUnited States DollarZARSouth African Rand
exchange_ratestringrequired
Default:
1Example:
1.0513135Currency exchange rate, including margin if applicable.
1.0 if the transaction currency matches your payout currency.fee_ratestringrequired
Example:
0.05Paddle fee rate that was applied to this transaction.
adjusted_payout_totalsobject | nullrequired
Breakdown of the payout total for a transaction after adjustments.
null until the transaction is completed.subtotalstringrequired
Example:
15000Total before tax and fees.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after tax.
feestringrequired
Example:
825Total fee taken by Paddle for this payout.
retained_feestringrequired
Example:
300Paddle fees retained for this adjustment.
chargeback_feeobjectrequired
Details of any chargeback fees incurred for this transaction.
amountstringrequired
Example:
1680Chargeback fee converted into the payout currency.
originalobject | nullrequired
Chargeback fee before conversion to the payout currency.
null when the chargeback fee is the same as the payout currency.amountstringrequired
Example:
1500Fee amount for this chargeback in the original currency.
currency_codestringrequired
Example:
USDThree-letter ISO 4217 currency code for the original chargeback fee.
Values
AUDAustralian DollarCADCanadian DollarEUREuroGBPPound SterlingUSDUnited States Dollar
earningsstringrequired
Example:
15675Total earnings for this payout. This is the subtotal minus the Paddle fee, excluding chargeback fees.
currency_codestringrequired
Three-letter ISO 4217 currency code used for the payout for this transaction. If your primary currency has changed, this reflects the primary currency at the time the transaction was billed.
Values
AUDAustralian DollarCADCanadian DollarCHFSwiss FrancCNYChinese YuanCZKCzech Koruna
+ Show all values− Hide values
DKKDanish KroneEUREuroGBPPound SterlingHUFHungarian ForintPLNPolish ZlotySEKSwedish KronaUSDUnited States DollarZARSouth African Rand
exchange_ratestringrequired
Example:
1.0513135Currency exchange rate, including margin if applicable.
1.0 if the transaction currency matches your payout currency.line_itemsarrayrequired
Information about line items for this transaction. Different from transaction
items as they include totals calculated by Paddle. Considered the source of truth for line item totals.price_idstringrequired
Example:
pri_01gsz8z1q1n00f12qt82y31smhPaddle ID for the price related to this transaction line item, prefixed with
pri_.Pattern:
^pri_[a-z\d]{26}$quantityintegerrequired
Quantity of this transaction line item.
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.
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. Reflects the entity at the time it was added to the transaction.
idstringrequired
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.
idstringrequired
Example:
txnitm_01gm302t81w94gyjpjpqypkzkfUnique Paddle ID for this transaction item, prefixed with
txnitm_. Used when working with adjustments.Pattern:
^txnitm_[a-z\d]{26}$paymentsarrayrequired
List of payment attempts for this transaction, including successful payments. Sorted by
created_at in descending order, so most recent attempts are returned first.payment_attempt_idstringrequired
Example:
497f776b-851d-4ebf-89ab-8ba0f75d2d6aUUID for this payment attempt.
stored_payment_method_idstringrequireddeprecated
Example:
7636e781-3969-49f4-9c77-8226232e28a6UUID for the stored payment method used for this payment attempt. Deprecated - use
payment_method_id instead.payment_method_idstring | nullrequired
Example:
paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1Unique Paddle ID for this payment method entity, prefixed with
paymtd_.Pattern:
^paymtd_[a-z\d]{26}$amountstringrequired
Example:
1050Amount for collection in the lowest denomination of a currency (e.g. cents for USD).
statusstringrequired
Status of this payment attempt.
Values
authorizedAuthorized but not captured. Payment attempt is incomplete.authorized_flaggedAuthorized but not captured because it has been flagged as potentially fraudulent. Payment attempt is incomplete.canceledPreviously authorized payment attempt has been canceled. Typically whenauthorized_flaggedpayment attempts are rejected.capturedPayment captured successfully. Payment attempt is complete.errorSomething went wrong and the payment attempt was unsuccessful. Check theerror_codefor more information.
+ Show all values− Hide values
action_requiredCustomer must complete an action for this payment attempt to proceed. Typically means that the payment attempt requires 3DS.pending_no_action_requiredResponse required from the bank or payment provider. Transaction is pending.createdNew payment attempt created.unknownPayment attempt status not known.droppedPayment attempt dropped by Paddle.
error_codestring | nullrequired
Reason why a payment attempt failed. Returns
null if payment captured successfully.Values
already_canceledCancellation not possible because the amount has already been canceled. Not typically returned for payments.already_refundedRefund is not possible because the amount has already been refunded. Not typically returned for payments.authentication_failedPayment required a 3DS2 authentication challenge. The customer completed the challenge but was not successful.blocked_cardPayment method issuer has indicated that the card cannot be used as it is frozen, lost, damaged, or stolen.canceledCustomer has requested that the mandate for recurring payments be canceled.
+ Show all values− Hide values
declinedPayment method has been declined, with no other information returned.declined_not_retryablePayment method has been declined, and the issuer has indicated that it should not be retried. This could mean the account is closed or the customer revoked authorization to charge the payment method.expired_cardPayment method issuer has indicated that this card is expired. Expired cards may also returninvalid_payment_details, depending on how a payment is routed.fraudPayment method issuer or payment service provider flagged this payment as potentially fraudulent.invalid_amountPayment method issuer or payment service provider cannot process a payment that is this high or low.invalid_payment_detailsPayment service provider has indicated the payment method isn't valid. This typically means that it's expired.expired_cardis returned by the payment method issuer, rather than the payment service provider.issuer_unavailablePayment service provider couldn't reach the payment method issuer.not_enough_balancePayment method declined because of insufficient funds, or fund limits being reached.preferred_network_not_supportedPayment method has been declined because the network scheme that the customer selected isn't supported by the payment service provider.psp_errorSomething went wrong with the payment service provider, with no other information returned.redacted_payment_methodPayment service provider didn't receive payment method information as they've been redacted.system_errorSomething went wrong with the Paddle platform. Try again later, or check status.paddle.com.transaction_not_permittedPayment method issuer doesn't allow this kind of payment because of limits on the account, or legal or compliance reasons.unknownPayment attempt unsuccessful, with no other information returned.
method_detailsobjectrequired
Information about the payment method used for a payment attempt.
typestringrequired
Type of payment method used for this payment attempt.
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 Korea.korea_localKorean payment methods, which includes over 20 payment options for the Korean market. Checkunderlying_payment_method.korea_localfor information about the Korean payment method used to pay.south_korea_local_cardKorean local credit or debit card.mb_wayMB WAY, a popular payment method in Portugal.naver_payNaver Pay, a popular payment method in Korea.offlinePayment recorded offline.paycoPayco, a popular payment method in Korea.paypalPayPal.pixPix, popular in Brazil. Available in early access.samsung_paySamsung Pay, a popular payment method in Korea.unknownPayment method not known.upiUnified Payments Interface (UPI), popular in India. Available in early access.wechat_payWeChat Pay, a popular payment method in China.wire_transferWire transfer, sometimes called bank transfer.
underlying_detailsobject | nullrequireddeprecated
Information about the underlying payment method used to pay. Populated for payment methods that offer multiple payment options, like
korea_local. Deprecated - use top-level type objects instead.korea_localobject | nullrequired
Information about the Korean payment method used to pay.
null unless the type is korea_local.typestringrequired
Type of Korean payment method used to pay.
Values
bcBC Card (BCard), a kind of card issued in Korea. (비씨카드)citiCard issued by Citi Bank in Korea. (한국씨티은행)hanaCard issued by Hana Bank in Korea. (하나카드)hyundaiHyundai Card, a credit card issued by Hyundai in Korea. (현대카드)jejuCard issued by Jeju Bank in Korea. (제주은행)
+ Show all values− Hide values
jeonbukCard issued by Jeonbuk Bank in Korea. (전북은행)kakaobankCard issued by Kakaobank in Korea. (주식회사 카카오뱅크)kakaopayKakaoPay digital wallet, popular in Korea. (카카오페이)kbankCard issued by K Bank in Korea. (케이뱅크)kdbbankCard issued by KDB Bank in Korea. (한국산업은행)kookminCard issued by Kookmin Bank in Korea. (국민은행)kwangjuCard issued by Kwangju Bank in Korea. (광주은행)lotteLotte Card, a credit card issued by the Lotte Corporation in Korea. (롯데카드)mgCard issued by MG Community Credit Cooperatives (KFCC) in Korea. (MG새마을금고)naverpaycardCard issued by Naver Pay in Korea. (네이버 페이)naverpaypointNaver Pay digital wallet, popular in Korea. (네이버 페이)nhNH Card, a card issued by Nonghyup Bank in Korea. (NH농협은행)paycoPayCo digital wallet, popular in Korea. (페이코)postCard issued by Korea Post. (우체국예금보험)samsungSamsung Card, a card issued by Samsung in Korea. (삼성카드)samsungpaySamsung Pay digital wallet, popular in Korea. (삼성 월렛)savingsbankCard issued by the Korean Federation of Savings Banks in Korea. (저축은행중앙회)shinhanCard issued by Shinhan Bank in Korea. (주식회사 신한은행)shinhyupCard issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (신한은행 신협)suhyupCard issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (수협은행)tossbankCard issued by Toss Bank in Korea. (토스뱅크)unknownUnderlying payment method not recognized.wooriCard issued by Woori Bank in Korea. (주식회사 우리은행)
south_korea_local_cardobject | nullrequired
Information about the Korean payment method used to pay.
typestring
Type of Korean payment method used to pay.
Values
bcBC Card (BCard), a kind of card issued in Korea. (비씨카드).citiCard issued by Citi Bank in Korea. (한국씨티은행).hanaCard issued by Hana Bank in Korea. (하나카드).hyundaiHyundai Card, a credit card issued by Hyundai in Korea. (현대카드).jejuCard issued by Jeju Bank in Korea. (제주은행).
+ Show all values− Hide values
jeonbukCard issued by Jeonbuk Bank in Korea. (전북은행).kakaobankkbankCard issued by K Bank in Korea. (케이뱅크).kdbbankCard issued by KDB Bank in Korea. (한국산업은행).kookminCard issued by Kookmin Bank in Korea. (국민은행).kwangjuCard issued by Kwangju Bank in Korea. (광주은행).lotteLotte Card, a credit card issued by the Lotte Corporation in Korea. (롯데카드).mgCard issued by MG Community Credit Cooperatives (KFCC) in Korea. (MG새마을금고).nhNH Card, a card issued by Nonghyup Bank in Korea. (NH농협은행).postCard issued by Korea Post. (우체국예금보험).samsungSamsung Card, a card issued by Samsung in Korea. (삼성카드).savingsbankCard issued by the Korean Federation of Savings Banks in Korea. (저축은행중앙회).shinhanCard issued by Shinhan Bank in Korea. (주식회사 신한은행).shinhyupCard issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (신한은행 신협).suhyupCard issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (수협은행).tossbankCard issued by Toss Bank in Korea. (토스뱅크).unknownUnderlying payment method not recognized.wooriCard issued by Woori Bank in Korea. (주식회사 우리은행).
last4string
Example:
4242Last four digits of the card used to pay.
cardobject | nullrequired
Card metadata
typestringrequired
Type of credit or debit card used to pay.
Values
american_expressAmerican Expressdiners_clubDiners ClubdiscoverDiscover CardjcbJCB Card, popular in JapanmadaMada Card, popular in Saudi Arabia
+ Show all values− Hide values
maestroMaestro (debit card)mastercardMastercardunion_payUnionPay, popular in ChinaunknownCard type unknownvisaVisa
last4stringrequired
Example:
4242Last four digits of the card used to pay.
expiry_monthintegerrequired
Example:
12Month of the expiry date of the card used to pay.
expiry_yearintegerrequired
Example:
2028Year of the expiry date of the card used to pay.
cardholder_namestringrequired
The name on the card used to pay.
paypalobject | nullrequired
PayPal payment attempt metadata
emailstringrequired
Example:
john.doe@example.comEmail address associated with the PayPal account.
referencestring | nullrequired
PayPal billing agreement identifier. Only populated for subscription payments where a billing agreement was created between the customer and PayPal.
null for one-off PayPal payments.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.
captured_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string.
checkoutobject | nullrequired
Paddle Checkout details for this transaction. Returned for automatically-collected transactions and where
billing_details.enable_checkout is true for manually-collected transactions; null otherwise.urlstring | nullrequired
Paddle Checkout URL for this transaction, composed of the URL passed in the request or your default payment URL +
?_ptxn= and the Paddle ID for this transaction.Length: 1–2048
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.
billed_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string.
revised_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string.
addressobject
Address for this transaction. Reflects the entity at the time it was added to the transaction, or its revision if
revised_at is not null. Returned when the include parameter is used with the address value and the transaction has an address_id.idstringrequired
Example:
add_01gm302t81w94gyjpjpqypkzkfUnique Paddle ID for this address entity, prefixed with
add_.Pattern:
^add_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this address, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$descriptionstring | nullrequired
Example:
Paddle.comMemorable description for this address.
Max length: 1024
first_linestring | nullrequired
Example:
3811 Ditmars BlvdFirst line of this address.
Max length: 1024
second_linestring | nullrequired
Second line of this address.
Max length: 1024
citystring | nullrequired
Example:
AstoriaCity of this address.
Max length: 200
postal_codestring | nullrequired
Example:
11105-1803ZIP or postal code of this address. Required for some countries.
Max length: 200
regionstring | nullrequired
Example:
NYState, county, or region of this address.
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
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.
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.
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
adjustmentsarray
List of adjustments for this transaction. Returned when the
include parameter is used with the adjustment value and the transaction has adjustments.idstringrequired
Example:
adj_01gya6twkp8y0tv1e19rsgst9mUnique Paddle ID for this adjustment entity, prefixed with
adj_.Pattern:
^adj_[a-z\d]{26}$actionstringrequired
How this adjustment impacts the related transaction.
Values
creditCredits some or all the related transaction.refundRefunds some or all the related transaction. Must be approved by Paddle in most cases.chargebackChargeback for the related transaction. Automatically created by Paddle when a customer successfully disputes a charge.chargeback_reverseReversal of a chargeback for the related transaction. Automatically created by Paddle when Paddle contests a chargeback successfully.chargeback_warningWarning of an upcoming chargeback for the related transaction. Automatically created by Paddle.
+ Show all values− Hide values
chargeback_warning_reverseReversal of a chargeback warning for the related transaction. Automatically created by Paddle.credit_reverseReversal of a credit for the related transaction. Automatically created by Paddle.
typestringrequired
Default:
partialExample:
partialType of adjustment. Use
full to adjust the grand total for the related transaction. Include an items array when creating a partial adjustment. If omitted, defaults to partial.Values
fullThe grand total for the related transaction is adjusted.partialSome line items for the related transaction are adjusted. Requiresitems.
transaction_idstringrequired
Example:
txn_01h04vsbhqc62t8hmd4z3b578cPaddle ID of the transaction that this adjustment is for, prefixed with
txn_.Pattern:
^txn_[a-z\d]{26}$subscription_idstring | nullrequired
Example:
sub_01h04vsc0qhwtsbsxh3422wjs4Unique Paddle ID for this subscription entity, prefixed with
sub_.Pattern:
^sub_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this adjustment, prefixed with
ctm_.
Set automatically by Paddle based on the customer_id of the related transaction.Pattern:
^ctm_[a-z\d]{26}$reasonstringrequired
Why this adjustment was created. Appears in the Paddle dashboard. Retained for record-keeping purposes.
credit_applied_to_balanceboolean | null
Whether this adjustment was applied to the related customer's credit balance. Only returned for
credit adjustments.currency_codestringrequired
Three-letter ISO 4217 currency code for this adjustment. Set automatically by Paddle based on the
currency_code of the related 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
statusstringrequired
Status of this adjustment. Set automatically by Paddle.
Most refunds for live accounts are created with the status of pending_approval until reviewed by Paddle, but some are automatically approved. For sandbox accounts, Paddle automatically approves refunds every ten minutes.
Credit adjustments don't require approval from Paddle, so they're created as approved.
Values
pending_approvalAdjustment is pending approval by Paddle. Most refunds for live accounts must be approved by Paddle.approvedAdjustment is approved. Default for credits. Set when Paddle approves a refund that waspending_approval.rejectedAdjustment has been rejected. Set when Paddle rejects a refund that waspending_approval.reversedAdjustment has been reversed. Set by Paddle when achargeback_reversalorcredit_reversaladjustment is created for this adjustment.
itemsarrayrequired
List of items on this adjustment. Required if
type is not populated or set to partial.Items: 1–100
idstringrequired
Example:
adjitm_01gw4rs4kex0prncwfne87ft8xUnique Paddle ID for this adjustment item, prefixed with
adjitm_.Pattern:
^adjitm_[a-z\d]{26}$item_idstringrequired
Example:
txnitm_01gm302t81w94gyjpjpqypkzkfPaddle ID for the transaction item that this adjustment item relates to, prefixed with
txnitm_.Pattern:
^txnitm_[a-z\d]{26}$typestringrequired
Example:
fullType of adjustment for this transaction item.
tax adjustments are automatically created by Paddle.
Include amount when creating a partial adjustment.Values
fullFull total for this transaction item is adjusted.partialPart of this transaction item is adjusted. Includeamountto specify the partial amount adjusted.taxTax for this transaction item is adjusted. Created automatically by Paddle.prorationA prorated amount for this transaction item is adjusted. Created automatically by Paddle in some cases when making changes to a subscription.
amountstring | nullrequired
Amount adjusted for this transaction item. Required when item
type is partial.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.
totalsobjectrequired
Breakdown of the total for an adjustment item.
subtotalstringrequired
Example:
15000Amount multiplied by quantity.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after tax.
totalsobjectrequired
Breakdown of the total for an adjustment.
subtotalstringrequired
Example:
15000Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after tax.
feestringrequired
Example:
300Total fee taken by Paddle for this adjustment.
retained_feestring
Example:
300Paddle fees retained for this adjustment.
earningsstringrequired
Example:
14700Total earnings. This is the subtotal minus the Paddle fee.
For tax adjustments, this value is negative, which means a positive effect in the transaction earnings.
This is because the fee is originally calculated from the transaction total, so if a tax adjustment is made,
then the fee portion of it is returned.
currency_codestringrequired
Example:
USDThree-letter ISO 4217 currency code used for this adjustment.
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
payout_totalsobject | nullrequired
Breakdown of how this adjustment affects your payout balance.
subtotalstringrequired
Example:
15000Adjustment total before tax and fees.
taxstringrequired
Example:
1500Total tax on the adjustment subtotal.
totalstringrequired
Example:
16500Adjustment total after tax.
feestringrequired
Example:
300Adjusted Paddle fee.
retained_feestringrequired
Example:
300Paddle fees retained for this adjustment.
chargeback_feeobject
Chargeback fees incurred for this adjustment. Only returned when the adjustment
action is chargeback or chargeback_warning.amountstringrequired
Example:
1680Chargeback fee converted into the payout currency.
originalobject | nullrequired
Chargeback fee before conversion to the payout currency.
null when the chargeback fee is the same as the payout currency.amountstringrequired
Example:
1500Fee amount for this chargeback in the original currency.
currency_codestringrequired
Example:
USDThree-letter ISO 4217 currency code for the original chargeback fee.
Values
AUDAustralian DollarCADCanadian DollarEUREuroGBPPound SterlingUSDUnited States Dollar
earningsstringrequired
Example:
15120Adjusted payout earnings. This is the adjustment total plus adjusted Paddle fees, excluding chargeback fees.
currency_codestringrequired
Three-letter ISO 4217 currency code used for the payout for this transaction. If your primary currency has changed, this reflects the primary currency at the time the transaction was billed.
Values
AUDAustralian DollarCADCanadian DollarCHFSwiss FrancCNYChinese YuanCZKCzech Koruna
+ Show all values− Hide values
DKKDanish KroneEUREuroGBPPound SterlingHUFHungarian ForintPLNPolish ZlotySEKSwedish KronaUSDUnited States DollarZARSouth African Rand
tax_rates_usedarrayrequired
tax_ratestringrequired
Example:
0.2Rate used to calculate tax for this adjustment.
totalsobjectrequired
Calculated totals for the tax applied to this adjustment.
subtotalstringrequired
Example:
15000Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after tax.
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.
adjustments_totalsobject
Object containing totals for all adjustments on a transaction. Returned when the
include parameter is used with the adjustments_totals value.subtotalstringrequired
Example:
15000Total before tax.
taxstringrequired
Example:
1500Total tax on the subtotal.
totalstringrequired
Example:
16500Total after tax.
feestringrequired
Example:
300Total fee taken by Paddle.
retained_feestringrequired
Example:
300Total gateway fee retained by Paddle.
earningsstringrequired
Example:
14700Total earnings. This is the subtotal minus the Paddle fee.
For tax adjustments, this value is negative, which means a positive effect in the transaction earnings.
This is because the fee is originally calculated from the transaction total, so if a tax adjustment is made,
then the fee portion of it is returned.
As a result, the earnings from all the adjustments performed could be either negative, positive or zero.
breakdownobjectrequired
Breakdown of the total adjustments by adjustment action.
creditstringrequired
Example:
8250Total amount of credit adjustments.
refundstringrequired
Example:
8250Total amount of refund adjustments.
chargebackstringrequired
Example:
0Total amount of chargeback adjustments.
currency_codestringrequired
Three-letter ISO 4217 currency code used for adjustments 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
businessobject
Business for this transaction. Reflects the entity at the time it was added to the transaction, or its revision if
revised_at is not null. Returned when the include parameter is used with the business value and the transaction has a business_id.idstringrequired
Example:
biz_01grrebrzaee2qj2fqqhmcyzajUnique Paddle ID for this business entity, prefixed with
biz_.Pattern:
^biz_[a-z\d]{26}$customer_idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysPaddle ID for the customer related to this business, prefixed with
cus_.Pattern:
^ctm_[a-z\d]{26}$namestringrequired
Name of this business.
Length: 1–1024
company_numberstring | nullrequired
Example:
123456789Company number for this business.
Max length: 1024
tax_identifierstring | nullrequired
Example:
AB0123456789Tax or VAT Number for this business.
Max length: 1024
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.
contactsarrayrequired
List of contacts related to this business, typically used for sending invoices.
Items: max 100, unique
namestringrequired
Full name of this contact.
Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this contact.
Length: 1–320
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.
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
customerobject
Customer for this transaction. Reflects the entity at the time it was added to the transaction, or its revision if
revised_at is not null. Returned when the include parameter is used with the customer value and the transaction has a customer_id.idstringrequired
Example:
ctm_01grnn4zta5a1mf02jjze7y2ysUnique Paddle ID for this customer entity, prefixed with
ctm_.Pattern:
^ctm_[a-z\d]{26}$namestring | nullrequired
Full name.
Max length: 1024
emailstring (email)required
Example:
test@paddle.comEmail address for this customer.
Length: 1–320
marketing_consentbooleanrequired
Default:
falseWhether this customer opted into marketing from you.
false unless customers check the marketing consent box
when using Paddle Checkout. Set automatically by Paddle.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.
localestringrequired
Default:
enValid IETF BCP 47 short form locale tag. If omitted, defaults to
en.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.
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
discountobject
Discount for this transaction. Reflects the entity at the time it was added to the transaction. Returned when the
include parameter is used with the discount value and the transaction has a discount_id.idstringrequired
Example:
dsc_01gv5kpg05xp104ek2fmgjwttfUnique Paddle ID for this discount, prefixed with
dsc_.Pattern:
^dsc_[a-z\d]{26}$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.
descriptionstringrequired
Short description for this discount for your reference. Not shown to customers.
Length: 1–500
enabled_for_checkoutbooleanrequired
Default:
trueWhether this discount can be redeemed by customers at checkout (
true) or not (false).codestring | nullrequired
Unique code that customers can use to apply this discount at checkout. Use letters and numbers only, up to 32 characters. Not case-sensitive.
Length: 1–32
Pattern:
^[a-zA-Z0-9]{1,32}$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%.
modestringrequired
Default:
standardDiscount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
standardStandard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.customNon-catalog discount. Can be created via the API, or by Paddle for checkout recovery discounts. Not returned when listing or shown in the Paddle dashboard.
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.currency_codestring | nullrequired
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
recurbooleanrequired
Default:
falseWhether this discount applies for multiple subscription billing periods (
true) or not (false).maximum_recurring_intervalsinteger | nullrequired
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
usage_limitinteger | nullrequired
Maximum number of times this discount can be redeemed. This is an overall limit for this discount, rather than a per-customer limit. null if this discount can be redeemed an unlimited amount of times.
Paddle counts a usage as a redemption on a checkout, transaction, or the initial application against a subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption.
Min: 1
restrict_toarray | nullrequired
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
expires_atstring (date-time) | nullrequired
Example:
2024-10-12T07:20:50.52ZRFC 3339 datetime string.
custom_dataobject | nullrequired
Example:
{"customer_reference_id":"abcd1234"}Your own structured key-value data.
times_usedintegerrequired
How many times this discount has been redeemed. Automatically incremented by Paddle.
Paddle counts a usage as a redemption on a checkout, transaction, or subscription. Transactions created for subscription renewals, midcycle changes, and one-time charges aren't considered a redemption.
discount_group_idstring | nullrequired
Example:
dsg_01js2gqehzccfkywgx1jk2mtspUnique Paddle ID for this discount group, prefixed with
dsg_.Pattern:
^dsg_[a-z\d]{26}$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.
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
available_payment_methodsarray
List of available payment methods for this transaction. Returned when the
include parameter is used with the available_payment_methods value.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.
{ "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3", "items": [ { "quantity": 50, "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea" }, { "quantity": 1, "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg" }, { "quantity": 1, "price_id": "pri_01gsz98e27ak2tyhexptwc58yk" } ]}{ "data": { "id": "txn_01hv8m0mnx3sj85e7gxc6kga03", "status": "ready", "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4", "address_id": "add_01hv8gq3318ktkfengj2r75gfx", "business_id": null, "custom_data": null, "origin": "api", "collection_mode": "manual", "subscription_id": null, "invoice_id": "inv_01hv8m0nn5nbvdejcvv9cpg8jf", "invoice_number": null, "billing_details": { "enable_checkout": false, "payment_terms": { "interval": "day", "frequency": 14 }, "purchase_order_number": "PO-123", "additional_information": null }, "billing_period": { "starts_at": "2024-04-12T00:00:00Z", "ends_at": "2025-04-11T23:59:00Z" }, "currency_code": "USD", "discount_id": "dsc_01gtgztp8fpchantd5g1wrksa3", "created_at": "2024-04-12T07:40:38.00704Z", "updated_at": "2024-04-12T10:00:03.871169408Z", "billed_at": null, "revised_at": null, "items": [ { "price": { "id": "pri_01gsz91wy9k1yn7kx82aafwvea", "description": "Annual", "type": "standard", "name": "Annual (per seat)", "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540", "billing_cycle": { "interval": "year", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "50000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "quantity": { "minimum": 1, "maximum": 100 }, "status": "active", "created_at": "2023-02-23T13:57:54.249913Z", "updated_at": "2024-04-05T14:32:00.471447Z", "import_meta": null }, "quantity": 50, "proration": null }, { "price": { "id": "pri_01gsz96z29d88jrmsf2ztbfgjg", "description": "Annual (recurring addon)", "type": "standard", "name": "Annual (recurring addon)", "product_id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "billing_cycle": { "interval": "year", "frequency": 1 }, "trial_period": null, "tax_mode": "account_setting", "unit_price": { "amount": "300000", "currency_code": "USD" }, "unit_price_overrides": [], "custom_data": null, "quantity": { "minimum": 1, "maximum": 1 }, "status": "active", "created_at": "2023-02-23T14:00:40.265185Z", "updated_at": "2024-03-25T14:31:18.587603Z", "import_meta": null }, "quantity": 1, "proration": null }, { "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 } ], "details": { "tax_rates_used": [ { "tax_rate": "0.08875", "totals": { "subtotal": "2819900", "discount": "281990", "tax": "225239", "total": "2763149" } } ], "totals": { "subtotal": "2819900", "tax": "225239", "discount": "281990", "total": "2763149", "grand_total": "2763149", "grand_total_tax": "225239", "fee": null, "credit": "0", "credit_to_balance": "0", "balance": "2763149", "earnings": null, "currency_code": "USD" }, "adjusted_totals": { "subtotal": "2537910", "tax": "225239", "total": "2763149", "grand_total": "2763149", "grand_total_tax": "225239", "fee": "0", "retained_fee": "0", "earnings": "0", "currency_code": "USD" }, "payout_totals": null, "adjusted_payout_totals": null, "line_items": [ { "id": "txnitm_01hv8vzz0sjdj6grvpxyyjsmvf", "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea", "quantity": 50, "totals": { "subtotal": "2500000", "tax": "199687", "discount": "250000", "total": "2449687" }, "product": { "id": "pro_01gsz4vmqbjk3x4vvtafffd540", "name": "AeroEdit Enterprise", "description": "The ultimate solution for organizations, featuring all Pro capabilities plus multi-user support, advanced data storage capabilities, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.", "type": "standard", "tax_category": "standard", "image_url": "https://paddle.s3.amazonaws.com/user/165798/Ws808ziTS76a6YbnMkiK_enterprise.png", "custom_data": { "features": { "aircraft_performance": true, "compliance_monitoring": true, "flight_log_management": true, "payment_by_invoice": true, "route_planning": true, "sso": true }, "suggested_addons": [], "upgrade_description": "Ready to reach new heights? Upgrade to enterprise to unlock single sign-on, payment by invoice, and dedicated account management." }, "status": "active", "created_at": "2023-02-23T12:44:34.923Z", "updated_at": "2024-04-05T15:58:28.309Z", "import_meta": null }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "50000", "tax": "3994", "discount": "5000", "total": "48994" }, "proration": null }, { "id": "txnitm_01hv8vzz0sjdj6grvpy1fzm46f", "price_id": "pri_01gsz96z29d88jrmsf2ztbfgjg", "quantity": 1, "totals": { "subtotal": "300000", "tax": "23962", "discount": "30000", "total": "293962" }, "product": { "id": "pro_01gsz92krfzy3hcx5h5rtgnfwz", "name": "VIP support", "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.", "type": "standard", "tax_category": "standard", "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png", "custom_data": null, "status": "active", "created_at": "2023-02-23T13:58:17.615Z", "updated_at": "2024-04-05T15:44:02.893Z", "import_meta": null }, "tax_rate": "0.08875", "unit_totals": { "subtotal": "300000", "tax": "23962", "discount": "30000", "total": "293962" }, "proration": null }, { "id": "txnitm_01hv8vzz0sjdj6grvpy6g84gyw", "price_id": "pri_01gsz98e27ak2tyhexptwc58yk", "quantity": 1, "totals": { "subtotal": "19900", "tax": "1590", "discount": "1990", "total": "19500" }, "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.08875", "unit_totals": { "subtotal": "19900", "tax": "1590", "discount": "1990", "total": "19500" }, "proration": null } ] }, "payments": [], "checkout": { "url": null } }, "meta": { "request_id": "ba7c3eb9-e88d-4239-be61-a47b8aceab66" }}