Docs

Get a transaction to update payment method

Returns a transaction that you can pass to a checkout to let customers update their payment details.

GET /subscriptions/{subscription_id}/update-payment-method-transaction

Returns a transaction that you can pass to a checkout to let customers update their payment details. Only for subscriptions where collection_mode is automatic.

The transaction returned depends on the status of the related subscription:

  • Where a subscription is past_due, it returns the most recent past_due transaction.
  • Where a subscription is active, it creates a new zero amount transaction for the items on a subscription.

You can use the returned checkout.url, or pass the returned transaction ID to Paddle.js to open a checkout to present customers with a way of updating their payment details.

The customer, address, business, discount, adjustments and adjustments_totals properties are only returned in the response if the API key has read permissions for those related entities.

Requires transaction.write permission.

Path parameters

subscription_idstringrequired
Paddle ID of the subscription entity to work with.

Response (200)

dataobjectrequired
idstringrequired
Example: txn_01h04vsbhqc62t8hmd4z3b578c
Unique 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
  • draft
    Transaction is missing required fields. Typically the first stage of a checkout before customer details are captured.
  • ready
    Transaction has all of the required fields to be marked as billed or completed.
  • billed
    Transaction has been updated to billed. Billed transactions get an invoice number and are considered a legal record. They cannot be changed. Typically used as part of an invoice workflow.
  • paid
    Transaction is fully paid, but has not yet been processed internally.
  • completed
    Transaction is fully paid and processed.
+ Show all values
  • canceled
    Transaction has been updated to canceled. If an invoice, it's no longer due.
  • past_due
    Transaction 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_01grnn4zta5a1mf02jjze7y2ys
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$
address_idstring | nullrequired
Example: add_01gm302t81w94gyjpjpqypkzkf
Unique Paddle ID for this address entity, prefixed with add_.
Pattern: ^add_[a-z\d]{26}$
business_idstring | nullrequired
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Unique 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
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
originstringrequired
Describes how this transaction was created.
Values
  • api
    Transaction created via the Paddle API.
  • subscription_charge
    Transaction created automatically by Paddle as a result of a one-time charge for a subscription.
  • subscription_payment_method_change
    Transaction created automatically as part of updating a payment method. May be a zero value transaction.
  • subscription_recurring
    Transaction created automatically by Paddle as a result of a subscription renewal.
  • subscription_update
    Transaction created automatically by Paddle as a result of an update to a subscription.
+ Show all values
  • web
    Transaction created automatically by Paddle.js for a checkout.
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Unique Paddle ID for this subscription entity, prefixed with sub_.
Pattern: ^sub_[a-z\d]{26}$
invoice_idstring | nullrequireddeprecated
Example: inv_01ghbk4xjn4qdsmstcwzgcgg35
Paddle 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-45678
Document number that is automatically generated by Paddle.
collection_modestringrequired
Default: automatic
How payment is collected for this transaction. automatic for checkout, manual for invoices.
Values
  • automatic
    Payment is collected automatically using a checkout initially, then using a payment method on file.
  • manual
    Payment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requires billing_details.
discount_idstring | nullrequired
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Unique 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: false
Whether 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
  • day
  • week
  • month
  • year
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.52Z
RFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 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_01gsz8z1q1n00f12qt82y31smh
Unique Paddle ID for this price, prefixed with pri_.
Pattern: ^pri_[a-z\d]{26}$
product_idstringrequired
Example: pro_01gsz97mq9pa4fkyy0wqenepkz
Paddle 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: standard
Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • custom
    Non-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.
  • standard
    Standard 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
  • day
  • week
  • month
  • year
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
  • day
  • week
  • month
  • year
frequencyintegerrequired
Amount of time.
Min: 1
requires_payment_methodbooleanrequired
Default: true
Whether 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_setting
How tax is calculated for this price.
Values
  • account_setting
    Prices use the setting from your account.
  • external
    Prices are exclusive of tax.
  • internal
    Prices are inclusive of tax.
  • location
    Prices 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
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South 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
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South 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: 1
Example: 1
Minimum quantity of the product related to this price that can be bought. Required if maximum set.
Range: 1–999999999
maximumintegerrequired
Default: 100
Example: 100
Maximum 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: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity 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-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name 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.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 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.52Z
RFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 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.2
Rate used to calculate tax for this transaction.
totalsobjectrequired
Calculated totals for the tax applied to this transaction.
subtotalstringrequired
Example: 15000
Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example: 0

Total 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: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total 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: 15000
Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example: 0

Total 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: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after discount and tax.
creditstringrequired
Example: 0
Total 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: 0
Additional credit generated from negative details.line_items. This credit is added to the customer balance.
balancestringrequired
Example: 16500
Total due on a transaction after credits and any payments.
grand_totalstringrequired
Example: 16500
Total due on a transaction after credits but before any payments.
grand_total_taxstringrequired
Example: 83
Net 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: 825
Total fee taken by Paddle for this transaction. null until the transaction is completed and the fee is processed.
earningsstring | nullrequired
Example: 15675
Total 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
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
adjusted_totalsobjectrequired
Breakdown of the totals for a transaction after adjustments.
subtotalstringrequired
Example: 15000
Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
grand_totalstringrequired
Example: 16500
Total due after credits but before any payments.
grand_total_taxstringrequired
Example: 83
Net 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: 825
Total fee taken by Paddle for this transaction. null until the transaction is completed and the fee is processed.
retained_feestringrequired
Example: 300
Total Paddle fees retained for this adjustment.
earningsstring | nullrequired
Example: 15675
Total 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
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South 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: 15000
Total before tax and fees.
discountstringrequired
Example: 0
Total 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: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
creditstringrequired
Example: 0
Total 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: 0
Additional credit generated from negative details.line_items. This credit is added to the customer balance.
balancestringrequired
Example: 16500
Total due on a transaction after credits and any payments.
grand_totalstringrequired
Example: 16500
Total due on a transaction after credits but before any payments.
grand_total_taxstringrequired
Example: 83
Net 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: 825
Total fee taken by Paddle for this payout.
earningsstringrequired
Example: 15675
Total 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
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • CNY
    Chinese Yuan
  • CZK
    Czech Koruna
+ Show all values
  • DKK
    Danish Krone
  • EUR
    Euro
  • GBP
    Pound Sterling
  • HUF
    Hungarian Forint
  • PLN
    Polish Zloty
  • SEK
    Swedish Krona
  • USD
    United States Dollar
  • ZAR
    South African Rand
exchange_ratestringrequired
Default: 1
Example: 1.0513135
Currency exchange rate, including margin if applicable. 1.0 if the transaction currency matches your payout currency.
fee_ratestringrequired
Example: 0.05
Paddle 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: 15000
Total before tax and fees.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
feestringrequired
Example: 825
Total fee taken by Paddle for this payout.
retained_feestringrequired
Example: 300
Paddle fees retained for this adjustment.
chargeback_feeobjectrequired
Details of any chargeback fees incurred for this transaction.
amountstringrequired
Example: 1680
Chargeback 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: 1500
Fee amount for this chargeback in the original currency.
currency_codestringrequired
Example: USD
Three-letter ISO 4217 currency code for the original chargeback fee.
Values
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • USD
    United States Dollar
earningsstringrequired
Example: 15675
Total 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
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • CNY
    Chinese Yuan
  • CZK
    Czech Koruna
+ Show all values
  • DKK
    Danish Krone
  • EUR
    Euro
  • GBP
    Pound Sterling
  • HUF
    Hungarian Forint
  • PLN
    Polish Zloty
  • SEK
    Swedish Krona
  • USD
    United States Dollar
  • ZAR
    South African Rand
exchange_ratestringrequired
Example: 1.0513135
Currency 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_01gsz8z1q1n00f12qt82y31smh
Paddle 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.52Z
RFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period ends.
tax_ratestringrequired
Example: 0.2
Rate 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: 15000
Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example: 0

Total 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: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after discount and tax.
totalsobjectrequired
Breakdown of a charge in the lowest denomination of a currency (e.g. cents for USD).
subtotalstringrequired
Example: 15000
Subtotal before discount, tax, and deductions. If an item, unit price multiplied by quantity.
discountstringrequired
Example: 0

Total 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: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total 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_01gsz97mq9pa4fkyy0wqenepkz
Unique 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: standard
Type of item. Standard items are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • custom
    Non-catalog item. Typically created for a specific transaction or subscription. Not returned when listing or shown in the Paddle dashboard.
  • standard
    Standard 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-goods
    Non-customizable digital files or media (not software) acquired with an up front payment that can be accessed without any physical product being delivered.
  • ebooks
    Digital books and educational material which is sold with permanent rights for use by the customer.
  • implementation-services
    Remote configuration, set-up, and integrating software on behalf of a customer.
  • professional-services
    Services that involve the application of your expertise and specialized knowledge of a software product.
  • saas
    Products that allow users to connect to and use online or cloud-based applications over the Internet.
+ Show all values
  • software-programming-services
  • standard
    Software products that are pre-written and can be downloaded and installed onto a local device.
  • training-services
    Training and education services related to software products.
  • website-hosting
    Cloud 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: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity 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-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name 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.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
idstringrequired
Example: txnitm_01gm302t81w94gyjpjpqypkzkf
Unique 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-8ba0f75d2d6a
UUID for this payment attempt.
stored_payment_method_idstringrequireddeprecated
Example: 7636e781-3969-49f4-9c77-8226232e28a6
UUID for the stored payment method used for this payment attempt. Deprecated - use payment_method_id instead.
payment_method_idstring | nullrequired
Example: paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1
Unique Paddle ID for this payment method entity, prefixed with paymtd_.
Pattern: ^paymtd_[a-z\d]{26}$
amountstringrequired
Example: 1050
Amount for collection in the lowest denomination of a currency (e.g. cents for USD).
statusstringrequired
Status of this payment attempt.
Values
  • authorized
    Authorized but not captured. Payment attempt is incomplete.
  • authorized_flagged
    Authorized but not captured because it has been flagged as potentially fraudulent. Payment attempt is incomplete.
  • canceled
    Previously authorized payment attempt has been canceled. Typically when authorized_flagged payment attempts are rejected.
  • captured
    Payment captured successfully. Payment attempt is complete.
  • error
    Something went wrong and the payment attempt was unsuccessful. Check the error_code for more information.
+ Show all values
  • action_required
    Customer must complete an action for this payment attempt to proceed. Typically means that the payment attempt requires 3DS.
  • pending_no_action_required
    Response required from the bank or payment provider. Transaction is pending.
  • created
    New payment attempt created.
  • unknown
    Payment attempt status not known.
  • dropped
    Payment attempt dropped by Paddle.
error_codestring | nullrequired
Reason why a payment attempt failed. Returns null if payment captured successfully.
Values
  • already_canceled
    Cancellation not possible because the amount has already been canceled. Not typically returned for payments.
  • already_refunded
    Refund is not possible because the amount has already been refunded. Not typically returned for payments.
  • authentication_failed
    Payment required a 3DS2 authentication challenge. The customer completed the challenge but was not successful.
  • blocked_card
    Payment method issuer has indicated that the card cannot be used as it is frozen, lost, damaged, or stolen.
  • canceled
    Customer has requested that the mandate for recurring payments be canceled.
+ Show all values
  • declined
    Payment method has been declined, with no other information returned.
  • declined_not_retryable
    Payment 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_card
    Payment method issuer has indicated that this card is expired. Expired cards may also return invalid_payment_details, depending on how a payment is routed.
  • fraud
    Payment method issuer or payment service provider flagged this payment as potentially fraudulent.
  • invalid_amount
    Payment method issuer or payment service provider cannot process a payment that is this high or low.
  • invalid_payment_details
    Payment service provider has indicated the payment method isn't valid. This typically means that it's expired. expired_card is returned by the payment method issuer, rather than the payment service provider.
  • issuer_unavailable
    Payment service provider couldn't reach the payment method issuer.
  • not_enough_balance
    Payment method declined because of insufficient funds, or fund limits being reached.
  • preferred_network_not_supported
    Payment method has been declined because the network scheme that the customer selected isn't supported by the payment service provider.
  • psp_error
    Something went wrong with the payment service provider, with no other information returned.
  • redacted_payment_method
    Payment service provider didn't receive payment method information as they've been redacted.
  • system_error
    Something went wrong with the Paddle platform. Try again later, or check status.paddle.com.
  • transaction_not_permitted
    Payment method issuer doesn't allow this kind of payment because of limits on the account, or legal or compliance reasons.
  • unknown
    Payment 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
  • alipay
    Alipay, popular in China.
  • apple_pay
    Apple Pay on a supported Apple device.
  • bancontact
    Bancontact, popular in Belgium.
  • blik
    BLIK, a popular payment method in Poland.
  • card
    Credit or debit card.
+ Show all values
  • google_pay
    Google Pay on a supported Android device, Chromebook, or Google Chrome browser.
  • ideal
    iDEAL, popular in the Netherlands.
  • kakao_pay
    Kakao Pay, a popular payment method in Korea.
  • korea_local
    Korean payment methods, which includes over 20 payment options for the Korean market. Check underlying_payment_method.korea_local for information about the Korean payment method used to pay.
  • south_korea_local_card
    Korean local credit or debit card.
  • mb_way
    MB WAY, a popular payment method in Portugal.
  • naver_pay
    Naver Pay, a popular payment method in Korea.
  • offline
    Payment recorded offline.
  • payco
    Payco, a popular payment method in Korea.
  • paypal
    PayPal.
  • pix
    Pix, popular in Brazil. Available in early access.
  • samsung_pay
    Samsung Pay, a popular payment method in Korea.
  • unknown
    Payment method not known.
  • upi
    Unified Payments Interface (UPI), popular in India. Available in early access.
  • wechat_pay
    WeChat Pay, a popular payment method in China.
  • wire_transfer
    Wire 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
  • bc
    BC Card (BCard), a kind of card issued in Korea. (비씨카드)
  • citi
    Card issued by Citi Bank in Korea. (한국씨티은행)
  • hana
    Card issued by Hana Bank in Korea. (하나카드)
  • hyundai
    Hyundai Card, a credit card issued by Hyundai in Korea. (현대카드)
  • jeju
    Card issued by Jeju Bank in Korea. (제주은행)
+ Show all values
  • jeonbuk
    Card issued by Jeonbuk Bank in Korea. (전북은행)
  • kakaobank
    Card issued by Kakaobank in Korea. (주식회사 카카오뱅크)
  • kakaopay
    KakaoPay digital wallet, popular in Korea. (카카오페이)
  • kbank
    Card issued by K Bank in Korea. (케이뱅크)
  • kdbbank
    Card issued by KDB Bank in Korea. (한국산업은행)
  • kookmin
    Card issued by Kookmin Bank in Korea. (국민은행)
  • kwangju
    Card issued by Kwangju Bank in Korea. (광주은행)
  • lotte
    Lotte Card, a credit card issued by the Lotte Corporation in Korea. (롯데카드)
  • mg
    Card issued by MG Community Credit Cooperatives (KFCC) in Korea. (MG새마을금고)
  • naverpaycard
    Card issued by Naver Pay in Korea. (네이버 페이)
  • naverpaypoint
    Naver Pay digital wallet, popular in Korea. (네이버 페이)
  • nh
    NH Card, a card issued by Nonghyup Bank in Korea. (NH농협은행)
  • payco
    PayCo digital wallet, popular in Korea. (페이코)
  • post
    Card issued by Korea Post. (우체국예금보험)
  • samsung
    Samsung Card, a card issued by Samsung in Korea. (삼성카드)
  • samsungpay
    Samsung Pay digital wallet, popular in Korea. (삼성 월렛)
  • savingsbank
    Card issued by the Korean Federation of Savings Banks in Korea. (저축은행중앙회)
  • shinhan
    Card issued by Shinhan Bank in Korea. (주식회사 신한은행)
  • shinhyup
    Card issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (신한은행 신협)
  • suhyup
    Card issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (수협은행)
  • tossbank
    Card issued by Toss Bank in Korea. (토스뱅크)
  • unknown
    Underlying payment method not recognized.
  • woori
    Card 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
  • bc
    BC Card (BCard), a kind of card issued in Korea. (비씨카드).
  • citi
    Card issued by Citi Bank in Korea. (한국씨티은행).
  • hana
    Card issued by Hana Bank in Korea. (하나카드).
  • hyundai
    Hyundai Card, a credit card issued by Hyundai in Korea. (현대카드).
  • jeju
    Card issued by Jeju Bank in Korea. (제주은행).
+ Show all values
  • jeonbuk
    Card issued by Jeonbuk Bank in Korea. (전북은행).
  • kakaobank
  • kbank
    Card issued by K Bank in Korea. (케이뱅크).
  • kdbbank
    Card issued by KDB Bank in Korea. (한국산업은행).
  • kookmin
    Card issued by Kookmin Bank in Korea. (국민은행).
  • kwangju
    Card issued by Kwangju Bank in Korea. (광주은행).
  • lotte
    Lotte Card, a credit card issued by the Lotte Corporation in Korea. (롯데카드).
  • mg
    Card issued by MG Community Credit Cooperatives (KFCC) in Korea. (MG새마을금고).
  • nh
    NH Card, a card issued by Nonghyup Bank in Korea. (NH농협은행).
  • post
    Card issued by Korea Post. (우체국예금보험).
  • samsung
    Samsung Card, a card issued by Samsung in Korea. (삼성카드).
  • savingsbank
    Card issued by the Korean Federation of Savings Banks in Korea. (저축은행중앙회).
  • shinhan
    Card issued by Shinhan Bank in Korea. (주식회사 신한은행).
  • shinhyup
    Card issued by the National Credit Unit Federation of Korea (Shinhyup) in Korea. (신한은행 신협).
  • suhyup
    Card issued by the National Federation of Fisheries Cooperation (Suhyup) in Korea. (수협은행).
  • tossbank
    Card issued by Toss Bank in Korea. (토스뱅크).
  • unknown
    Underlying payment method not recognized.
  • woori
    Card issued by Woori Bank in Korea. (주식회사 우리은행).
last4string
Example: 4242
Last four digits of the card used to pay.
cardobject | nullrequired
Card metadata
typestringrequired
Type of credit or debit card used to pay.
Values
  • american_express
    American Express
  • diners_club
    Diners Club
  • discover
    Discover Card
  • jcb
    JCB Card, popular in Japan
  • mada
    Mada Card, popular in Saudi Arabia
+ Show all values
  • maestro
    Maestro (debit card)
  • mastercard
    Mastercard
  • union_pay
    UnionPay, popular in China
  • unknown
    Card type unknown
  • visa
    Visa
last4stringrequired
Example: 4242
Last four digits of the card used to pay.
expiry_monthintegerrequired
Example: 12
Month of the expiry date of the card used to pay.
expiry_yearintegerrequired
Example: 2028
Year 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.com
Email 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.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
captured_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 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.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
billed_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string.
revised_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string.
customerobject
Related customer for this transaction. Only returned if the API key has a Customers (Read) permission.
idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Unique 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.com
Email address for this customer.
Length: 1–320
marketing_consentbooleanrequired
Default: false
Whether 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: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
localestringrequired
Default: en
Valid IETF BCP 47 short form locale tag. If omitted, defaults to en.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 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-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
addressobject
Related address for this transaction. Only returned if the API key has an Addresses (Read) permission.
idstringrequired
Example: add_01gm302t81w94gyjpjpqypkzkf
Unique Paddle ID for this address entity, prefixed with add_.
Pattern: ^add_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID for the customer related to this address, prefixed with cus_.
Pattern: ^ctm_[a-z\d]{26}$
descriptionstring | nullrequired
Example: Paddle.com
Memorable description for this address.
Max length: 1024
first_linestring | nullrequired
Example: 3811 Ditmars Blvd
First line of this address.
Max length: 1024
second_linestring | nullrequired
Second line of this address.
Max length: 1024
citystring | nullrequired
Example: Astoria
City of this address.
Max length: 200
postal_codestring | nullrequired
Example: 11105-1803
ZIP or postal code of this address. Required for some countries.
Max length: 200
regionstring | nullrequired
Example: NY
State, 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
  • AD
    Andorra
  • AE
    United Arab Emirates
  • AG
    Antigua and Barbuda
  • AI
    Anguilla
  • AL
    Albania
+ Show all values
  • AM
    Armenia
  • AO
    Angola
  • AR
    Argentina
  • AS
    American Samoa
  • AT
    Austria
  • AU
    Australia
  • AW
    Aruba
  • AX
    Åland Islands
  • AZ
    Azerbaijan
  • BA
    Bosnia and Herzegovina
  • BB
    Barbados
  • BD
    Bangladesh
  • BE
    Belgium
  • BF
    Burkina Faso
  • BG
    Bulgaria
  • BH
    Bahrain
  • BI
    Burundi
  • BJ
    Benin
  • BL
    Saint Barthélemy
  • BM
    Bermuda
  • BN
    Brunei
  • BO
    Bolivia
  • BQ
    Caribbean Netherlands (Bonaire, Sint Eustatius, and Saba)
  • BR
    Brazil
  • BS
    Bahamas
  • BT
    Bhutan
  • BV
    Bouvet Island
  • BW
    Botswana
  • BZ
    Belize
  • CA
    Canada
  • CC
    Cocos Islands
  • CG
    Republic of Congo
  • CH
    Switzerland
  • CI
    Côte d'Ivoire (Ivory Coast)
  • CK
    Cook Islands
  • CL
    Chile
  • CM
    Cameroon
  • CN
    China
  • CO
    Colombia
  • CR
    Costa Rica
  • CV
    Cape Verde
  • CW
    Curaçao
  • CX
    Christmas Island
  • CY
    Cyprus
  • CZ
    Czechia (Czech Republic)
  • DE
    Germany
  • DJ
    Djibouti
  • DK
    Denmark
  • DM
    Dominica
  • DO
    Dominican Republic
  • DZ
    Algeria
  • EC
    Ecuador
  • EE
    Estonia
  • EG
    Egypt
  • EH
    Western Sahara
  • ER
    Eritrea
  • ES
    Spain
  • ET
    Ethiopia
  • FI
    Finland
  • FJ
    Fiji
  • FK
    Falkland Islands
  • FM
    Micronesia
  • FO
    Faroe Islands
  • FR
    France
  • GA
    Gabon
  • GB
    United Kingdom
  • GD
    Grenada
  • GE
    Georgia
  • GF
    French Guiana
  • GG
    Guernsey
  • GH
    Ghana
  • GI
    Gibraltar
  • GL
    Greenland
  • GM
    Gambia
  • GN
    Guinea
  • GP
    Guadeloupe
  • GQ
    Equatorial Guinea
  • GR
    Greece
  • GS
    South Georgia and the South Sandwich Islands
  • GT
    Guatemala
  • GU
    Guam
  • GW
    Guinea-Bissau
  • GY
    Guyana
  • HK
    Hong Kong
  • HM
    Heard Island and McDonald Islands
  • HN
    Honduras
  • HR
    Croatia
  • HU
    Hungary
  • ID
    Indonesia
  • IE
    Ireland
  • IL
    Israel
  • IM
    Isle of Man
  • IN
    India
  • IO
    British Indian Ocean Territory
  • IQ
    Iraq
  • IS
    Iceland
  • IT
    Italy
  • JE
    Jersey
  • JM
    Jamaica
  • JO
    Jordan
  • JP
    Japan
  • KE
    Kenya
  • KG
    Kyrgyzstan
  • KH
    Cambodia
  • KI
    Kiribati
  • KM
    Comoros
  • KN
    Saint Kitts and Nevis
  • KR
    South Korea
  • KW
    Kuwait
  • KY
    Cayman Islands
  • KZ
    Kazakhstan
  • LA
    Lao People's Democratic Republic (Laos)
  • LB
    Lebanon
  • LC
    Saint Lucia
  • LI
    Liechtenstein
  • LK
    Sri Lanka
  • LR
    Liberia
  • LS
    Lesotho
  • LT
    Lithuania
  • LU
    Luxembourg
  • LV
    Latvia
  • MA
    Morocco
  • MC
    Monaco
  • MD
    Moldova
  • ME
    Montenegro
  • MF
    Saint Martin
  • MG
    Madagascar
  • MH
    Marshall Islands
  • MK
    Macedonia
  • MN
    Mongolia
  • MO
    Macao
  • MP
    Northern Mariana Islands
  • MQ
    Martinique
  • MR
    Mauritania
  • MS
    Montserrat
  • MT
    Malta
  • MU
    Mauritius
  • MV
    Maldives
  • MW
    Malawi
  • MX
    Mexico
  • MY
    Malaysia
  • MZ
    Mozambique
  • NA
    Namibia
  • NC
    New Caledonia
  • NE
    Niger
  • NF
    Norfolk Island
  • NG
    Nigeria
  • NL
    Netherlands
  • NO
    Norway
  • NP
    Nepal
  • NR
    Nauru
  • NU
    Niue
  • NZ
    New Zealand
  • OM
    Oman
  • PA
    Panama
  • PE
    Peru
  • PF
    French Polynesia
  • PG
    Papua New Guinea
  • PH
    Philippines
  • PK
    Pakistan
  • PL
    Poland
  • PM
    Saint Pierre and Miquelon
  • PN
    Pitcairn
  • PR
    Puerto Rico
  • PS
    Palestinian territories
  • PT
    Portugal
  • PW
    Palau
  • PY
    Paraguay
  • QA
    Qatar
  • RE
    Reunion
  • RO
    Romania
  • RS
    Republic of Serbia
  • RW
    Rwanda
  • SA
    Saudi Arabia
  • SB
    Solomon Islands
  • SC
    Seychelles
  • SE
    Sweden
  • SG
    Singapore
  • SH
    Saint Helena
  • SI
    Slovenia
  • SJ
    Svalbard and Jan Mayen
  • SK
    Slovakia
  • SL
    Sierra Leone
  • SM
    San Marino
  • SN
    Senegal
  • SR
    Suriname
  • ST
    São Tomé and Príncipe
  • SV
    El Salvador
  • SX
    Sint Maarten
  • SZ
    Swaziland
  • TC
    Turks and Caicos Islands
  • TD
    Chad
  • TF
    French Southern and Antarctic Lands
  • TG
    Togo
  • TH
    Thailand
  • TJ
    Tajikistan
  • TK
    Tokelau
  • TL
    Timor-Leste
  • TM
    Turkmenistan
  • TN
    Tunisia
  • TO
    Tonga
  • TR
    Turkey
  • TT
    Trinidad and Tobago
  • TV
    Tuvalu
  • TW
    Taiwan
  • TZ
    Tanzania
  • UA
    Ukraine
  • UG
    Uganda
  • UM
    United States Minor Outlying Islands
  • US
    United States
  • UY
    Uruguay
  • UZ
    Uzbekistan
  • VA
    Holy See (Vatican City)
  • VC
    Saint Vincent and the Grenadines
  • VG
    British Virgin Islands
  • VI
    U.S. Virgin Islands
  • VN
    Vietnam
  • VU
    Vanuatu
  • WF
    Wallis and Futuna
  • WS
    Samoa
  • XK
    Kosovo
  • YT
    Mayotte
  • ZA
    South Africa
  • ZM
    Zambia
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 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-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
businessobject
Related business for this transaction. Only returned if a business exists for this transaction and the API key has a Businesses (Read) permission.
idstringrequired
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Unique Paddle ID for this business entity, prefixed with biz_.
Pattern: ^biz_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle 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: 123456789
Company number for this business.
Max length: 1024
tax_identifierstring | nullrequired
Example: AB0123456789
Tax or VAT Number for this business.
Max length: 1024
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity 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.com
Email address for this contact.
Length: 1–320
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 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-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
discountobject
Related discount for this transaction. Only returned if a discount exists for this transaction and the API key has a Discounts (Read) permission.
idstringrequired
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Unique Paddle ID for this discount, prefixed with dsc_.
Pattern: ^dsc_[a-z\d]{26}$
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity 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: true
Whether 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
  • flat
    Discounts a checkout or transaction by a flat amount, for example -$100. Requires currency_code.
  • flat_per_seat
    Discounts a checkout or transaction by a flat amount per unit, for example -$100 per user. Requires currency_code.
  • percentage
    Discounts a checkout or transaction by a percentage of the total, for example -10%. Maximum 100%.
modestringrequired
Default: standard
Discount mode. Standard discounts are considered part of your catalog and are shown in the Paddle dashboard.
Values
  • standard
    Standard discount. Can be considered part of your catalog and reused across transactions and subscriptions easily.
  • custom
    Non-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
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
recurbooleanrequired
Default: false
Whether 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.52Z
RFC 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_01js2gqehzccfkywgx1jk2mtsp
Unique 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.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 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-1936a6d818ab
Reference or identifier for this entity from the provider where it was imported from.
Length: 1–200
imported_fromstringrequired
Example: paddle_classic
Name of the platform or provider where this entity was imported from.
Length: 1–200
adjustmentsarrayrequired
Related adjustments for this transaction. Only returned if adjustments exist for this transaction and the API key has an Adjustments (Read) permission.
idstringrequired
Example: adj_01gya6twkp8y0tv1e19rsgst9m
Unique Paddle ID for this adjustment entity, prefixed with adj_.
Pattern: ^adj_[a-z\d]{26}$
actionstringrequired
How this adjustment impacts the related transaction.
Values
  • credit
    Credits some or all the related transaction.
  • refund
    Refunds some or all the related transaction. Must be approved by Paddle in most cases.
  • chargeback
    Chargeback for the related transaction. Automatically created by Paddle when a customer successfully disputes a charge.
  • chargeback_reverse
    Reversal of a chargeback for the related transaction. Automatically created by Paddle when Paddle contests a chargeback successfully.
  • chargeback_warning
    Warning of an upcoming chargeback for the related transaction. Automatically created by Paddle.
+ Show all values
  • chargeback_warning_reverse
    Reversal of a chargeback warning for the related transaction. Automatically created by Paddle.
  • credit_reverse
    Reversal of a credit for the related transaction. Automatically created by Paddle.
typestringrequired
Default: partial
Example: partial
Type 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
  • full
    The grand total for the related transaction is adjusted.
  • partial
    Some line items for the related transaction are adjusted. Requires items.
transaction_idstringrequired
Example: txn_01h04vsbhqc62t8hmd4z3b578c
Paddle ID of the transaction that this adjustment is for, prefixed with txn_.
Pattern: ^txn_[a-z\d]{26}$
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Unique Paddle ID for this subscription entity, prefixed with sub_.
Pattern: ^sub_[a-z\d]{26}$
customer_idstringrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle 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
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South 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_approval
    Adjustment is pending approval by Paddle. Most refunds for live accounts must be approved by Paddle.
  • approved
    Adjustment is approved. Default for credits. Set when Paddle approves a refund that was pending_approval.
  • rejected
    Adjustment has been rejected. Set when Paddle rejects a refund that was pending_approval.
  • reversed
    Adjustment has been reversed. Set by Paddle when a chargeback_reversal or credit_reversal adjustment 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_01gw4rs4kex0prncwfne87ft8x
Unique Paddle ID for this adjustment item, prefixed with adjitm_.
Pattern: ^adjitm_[a-z\d]{26}$
item_idstringrequired
Example: txnitm_01gm302t81w94gyjpjpqypkzkf
Paddle ID for the transaction item that this adjustment item relates to, prefixed with txnitm_.
Pattern: ^txnitm_[a-z\d]{26}$
typestringrequired
Example: full
Type of adjustment for this transaction item. tax adjustments are automatically created by Paddle. Include amount when creating a partial adjustment.
Values
  • full
    Full total for this transaction item is adjusted.
  • partial
    Part of this transaction item is adjusted. Include amount to specify the partial amount adjusted.
  • tax
    Tax for this transaction item is adjusted. Created automatically by Paddle.
  • proration
    A 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.52Z
RFC 3339 datetime string of when this period starts.
ends_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this period ends.
totalsobjectrequired
Breakdown of the total for an adjustment item.
subtotalstringrequired
Example: 15000
Amount multiplied by quantity.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
totalsobjectrequired
Breakdown of the total for an adjustment.
subtotalstringrequired
Example: 15000
Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
feestringrequired
Example: 300
Total fee taken by Paddle for this adjustment.
retained_feestring
Example: 300
Paddle fees retained for this adjustment.
earningsstringrequired
Example: 14700
Total 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: USD
Three-letter ISO 4217 currency code used for this adjustment.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
payout_totalsobject | nullrequired
Breakdown of how this adjustment affects your payout balance.
subtotalstringrequired
Example: 15000
Adjustment total before tax and fees.
taxstringrequired
Example: 1500
Total tax on the adjustment subtotal.
totalstringrequired
Example: 16500
Adjustment total after tax.
feestringrequired
Example: 300
Adjusted Paddle fee.
retained_feestringrequired
Example: 300
Paddle 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: 1680
Chargeback 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: 1500
Fee amount for this chargeback in the original currency.
currency_codestringrequired
Example: USD
Three-letter ISO 4217 currency code for the original chargeback fee.
Values
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • USD
    United States Dollar
earningsstringrequired
Example: 15120
Adjusted 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
  • AUD
    Australian Dollar
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • CNY
    Chinese Yuan
  • CZK
    Czech Koruna
+ Show all values
  • DKK
    Danish Krone
  • EUR
    Euro
  • GBP
    Pound Sterling
  • HUF
    Hungarian Forint
  • PLN
    Polish Zloty
  • SEK
    Swedish Krona
  • USD
    United States Dollar
  • ZAR
    South African Rand
tax_rates_usedarrayrequired
tax_ratestringrequired
Example: 0.2
Rate used to calculate tax for this adjustment.
totalsobjectrequired
Calculated totals for the tax applied to this adjustment.
subtotalstringrequired
Example: 15000
Total before tax. For tax adjustments, the value is 0.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
adjustments_totalsobject
Object containing totals for all adjustments on this transaction. Only returned if the API key has an Adjustments (Read) permission.
subtotalstringrequired
Example: 15000
Total before tax.
taxstringrequired
Example: 1500
Total tax on the subtotal.
totalstringrequired
Example: 16500
Total after tax.
feestringrequired
Example: 300
Total fee taken by Paddle.
retained_feestringrequired
Example: 300
Total gateway fee retained by Paddle.
earningsstringrequired
Example: 14700
Total 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: 8250
Total amount of credit adjustments.
refundstringrequired
Example: 8250
Total amount of refund adjustments.
chargebackstringrequired
Example: 0
Total amount of chargeback adjustments.
currency_codestringrequired
Three-letter ISO 4217 currency code used for adjustments for this transaction.
Values
  • USD
    United States Dollar
  • EUR
    Euro
  • GBP
    Pound Sterling
  • JPY
    Japanese Yen
  • AUD
    Australian Dollar
+ Show all values
  • CAD
    Canadian Dollar
  • CHF
    Swiss Franc
  • HKD
    Hong Kong Dollar
  • SGD
    Singapore Dollar
  • SEK
    Swedish Krona
  • ARS
    Argentine Peso
  • BRL
    Brazilian Real
  • CLP
    Chilean Peso
  • CNY
    Chinese Yuan
  • COP
    Colombian Peso
  • CZK
    Czech Koruna
  • DKK
    Danish Krone
  • HUF
    Hungarian Forint
  • ILS
    Israeli Shekel
  • INR
    Indian Rupee
  • KRW
    South Korean Won
  • MXN
    Mexican Peso
  • NOK
    Norwegian Krone
  • NZD
    New Zealand Dollar
  • PEN
    Peruvian Sol
  • PLN
    Polish Zloty
  • RUB
    Russian Ruble
  • THB
    Thai Baht
  • TRY
    Turkish Lira
  • TWD
    New Taiwan Dollar
  • UAH
    Ukrainian Hryvnia
  • VND
    Vietnamese Dong
  • ZAR
    South African Rand
available_payment_methodsarrayrequired
List of payment methods available for this transaction.
Values
  • alipay
    Alipay, popular in China.
  • apple_pay
    Apple Pay on a supported Apple device.
  • bancontact
    Bancontact, popular in Belgium.
  • blik
    BLIK, a popular payment method in Poland.
  • card
    Credit or debit card.
+ Show all values
  • google_pay
    Google Pay on a supported Android device, Chromebook, or Google Chrome browser.
  • ideal
    iDEAL, popular in the Netherlands.
  • kakao_pay
    Kakao Pay, a popular payment method in South Korea.
  • korea_local
    Korean payment methods, which includes over 20 payment options for the Korean market.
  • naver_pay
    Naver Pay, a popular payment method in South Korea.
  • payco
    Payco, a popular payment method in South Korea.
  • samsung_pay
    Samsung Pay, a popular payment method in South Korea.
  • south_korea_local_card
    Korean local credit or debit card.
  • mb_way
    MB WAY, a popular payment method in Portugal.
  • paypal
    PayPal.
  • pix
    Pix, popular in Brazil.
  • upi
    Unified Payments Interface (UPI), popular in India.
  • wechat_pay
    WeChat Pay, a popular payment method in China.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
Response
{
  "data": {
    "id": "txn_01jspbekkwn03q6zp8bezp3tv2",
    "status": "ready",
    "customer_id": "ctm_01jspbafm96p2ppbe85921nf6p",
    "address_id": "add_01jspbafmrn485m030p7kx9dbr",
    "business_id": null,
    "custom_data": null,
    "origin": "subscription_payment_method_change",
    "collection_mode": "automatic",
    "subscription_id": "sub_01jspbbyjtkycfmjf7ye85yvp2",
    "invoice_id": null,
    "invoice_number": null,
    "discount_id": null,
    "billing_details": null,
    "billing_period": {
      "starts_at": "2025-04-25T11:29:46.915899Z",
      "ends_at": "2025-04-25T11:29:46.915899Z"
    },
    "currency_code": "USD",
    "created_at": "2025-04-25T11:31:14.986430069Z",
    "updated_at": "2025-04-25T11:31:14.986430069Z",
    "billed_at": null,
    "revised_at": null,
    "items": [
      {
        "price": {
          "id": "pri_01jspaymrp8mpq0fxdgwxy5vwh",
          "product_id": "pro_01jspay5m2ry6s10w1m9xfthvz",
          "type": "standard",
          "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
          "name": "AeroEdit VIP",
          "billing_cycle": {
            "interval": "month",
            "frequency": 1
          },
          "tax_mode": "account_setting",
          "unit_price": {
            "amount": "30000",
            "currency_code": "USD"
          },
          "unit_price_overrides": [],
          "custom_data": null,
          "status": "active",
          "quantity": {
            "minimum": 1,
            "maximum": 1
          },
          "import_meta": null,
          "created_at": "2025-04-25T11:22:31.574394Z",
          "updated_at": "2025-04-25T11:22:31.574395Z",
          "trial_period": null
        },
        "quantity": 1,
        "proration": {
          "rate": "0",
          "billing_period": {
            "starts_at": "2025-04-25T11:29:46.915899Z",
            "ends_at": "2025-05-25T11:29:46.915899Z"
          }
        }
      }
    ],
    "details": {
      "tax_rates_used": [
        {
          "tax_rate": "0.08875",
          "totals": {
            "subtotal": "0",
            "discount": "0",
            "tax": "0",
            "total": "0"
          }
        }
      ],
      "totals": {
        "subtotal": "0",
        "tax": "0",
        "discount": "0",
        "total": "0",
        "grand_total": "0",
        "grand_total_tax": "0",
        "fee": null,
        "credit": "0",
        "currency_code": "USD",
        "balance": "0",
        "credit_to_balance": "0",
        "earnings": null
      },
      "adjusted_totals": {
        "subtotal": "0",
        "tax": "0",
        "total": "0",
        "grand_total": "0",
        "grand_total_tax": "0",
        "fee": null,
        "earnings": null,
        "currency_code": "USD",
        "retained_fee": "0"
      },
      "payout_totals": null,
      "adjusted_payout_totals": null,
      "line_items": [
        {
          "id": "txnitm_01jspbekwp0ajkz6qxj4wdmzf3",
          "price_id": "pri_01jspaymrp8mpq0fxdgwxy5vwh",
          "quantity": 1,
          "totals": {
            "subtotal": "0",
            "tax": "0",
            "discount": "0",
            "total": "0"
          },
          "product": {
            "id": "pro_01jspay5m2ry6s10w1m9xfthvz",
            "name": "AeroEdit VIP",
            "type": "standard",
            "tax_category": "standard",
            "description": "Get exclusive access to our expert team of product specialists, available to help you make the most of your AeroEdit subscription.",
            "image_url": "https://paddle.s3.amazonaws.com/user/165798/qgyipKJwRtq98YNboipo_vip-support.png",
            "custom_data": null,
            "status": "active",
            "import_meta": null,
            "created_at": "2025-04-25T11:22:16.066Z",
            "updated_at": "2025-04-25T11:22:16.066Z"
          },
          "tax_rate": "0.08875",
          "unit_totals": {
            "subtotal": "0",
            "discount": "0",
            "tax": "0",
            "total": "0"
          },
          "proration": {
            "rate": "0",
            "billing_period": {
              "starts_at": "2025-04-25T11:29:46.915899Z",
              "ends_at": "2025-05-25T11:29:46.915899Z"
            }
          }
        }
      ]
    },
    "payments": [],
    "checkout": {
      "url": "https://aeroedit.com/pay?_ptxn=txn_01hv8zbfzrnfr6b4hfexhk4e7h"
    },
    "customer": {
      "id": "ctm_01jspbafm96p2ppbe85921nf6p",
      "name": null,
      "email": "sam@example.com",
      "locale": "en",
      "marketing_consent": false,
      "custom_data": null,
      "status": "active",
      "created_at": "2025-04-25T11:28:59.529Z",
      "updated_at": "2025-04-25T11:28:59.529Z",
      "import_meta": null
    },
    "address": {
      "id": "add_01jspbafmrn485m030p7kx9dbr",
      "customer_id": "ctm_01jspbafm96p2ppbe85921nf6p",
      "description": null,
      "first_line": null,
      "second_line": null,
      "city": null,
      "postal_code": "10021",
      "region": null,
      "country_code": "US",
      "status": "active",
      "custom_data": null,
      "import_meta": null,
      "created_at": "2025-04-25T11:28:59.544Z",
      "updated_at": "2025-04-25T11:28:59.544Z"
    },
    "adjustments_totals": {
      "subtotal": "0",
      "tax": "0",
      "total": "0",
      "fee": "0",
      "earnings": "0",
      "breakdown": {
        "credit": "0",
        "refund": "0",
        "chargeback": "0"
      },
      "currency_code": "USD",
      "retained_fee": "0"
    },
    "available_payment_methods": [
      "apple_pay",
      "card",
      "paypal",
      "google_pay"
    ],
    "adjustments": []
  },
  "meta": {
    "request_id": "c73663c7-7308-4af5-9cf2-4cc9f7372196"
  }
}

Was this page helpful?