Checkout Parameters

Passing additional parameters allows you to modify the behavior of the Paddle checkout, for example to pre-fill a buyer’s email address or set a custom price. Either JavaScript parameters or HTML attributes can be used, depending on your integration.

How to pass in parameters

The method of specifying checkout parameters depends on whether you have implemented your checkout using the paddle_button class or are invoking the checkout yourself by calling the Paddle.Checkout.open() method.

If you are using the paddle_button class, checkout properties must be set using data attributes on the button itself (see Button Attribute column in the table below). If you are calling Paddle.Checkout.open(), the properties should be set by specifying parameters in the method call (see JavaScript Attribute column below).

Checkout Properties

When creating checkouts either via the Paddle Checkout Buttons, or invoking directly using Paddle.Checkout.open() there are a number of options available to you to customise the checkout experience, or pre-fill data.

A list of these properties are below and can be used on both Checkout Buttons, or with the open() method.

Property Name Description Button Attribute JavaScript Attribute Required
Product ID The ID of the Paddle Product or Subscription this checkout is for. data-product product Yes
Success Redirect A URL to redirect to upon checkout completion. data-success success No
Success Callback A Javascript function to call upon checkout completion. data-success-callback successCallback No
Close Callback A Javascript function to call upon checkout close. data-close-callback closeCallback No
Load Callback A Javascript function to call upon checkout loaded. data-load-callback loadCallback No
Price Override Overrides the price of the checkout. (Requires Authentication) data-price price No
Price Override Auth Authenticates the checkout price override value. (See Docs) data-auth auth Yes (if price is also set)
Locale Force the checkout to a specific locale data-locale locale No
Trial Days Overrides the default number of trial days for the subscription being purchased. data-trial-days trialDays No
Trial Days Auth Authenticates the value of the ‘Trial Days’ field. Value should be the ‘Trial Days’ value, hashed with the product’s “Checkout Secret Key” data-trial-days-auth trialDaysAuth Yes (if trialDays is also set)
Marketing Consent Pre-fills the consent to market the users. data-marketing-consent marketingConsent Yes (if email is also set)
Email Pre-fills the customer ‘Email’ field on the checkout. data-email email No
Country Pre-fills the customer ‘Country’ field on the checkout. data-country country No
ZIP/Postal Code Pre-fills the customer ‘ZIP/Postcode’ field on the checkout.

N.b. It is highly recommended to pass country (above) when setting a postcode.
data-postcode postcode No
Passthrough Ancillary meta-data you wish to store with the checkout. Will be sent alongside all webhooks associated with the order. data-passthrough passthrough No
Coupon Pre-fills a coupon code on the checkout. data-coupon coupon No
Quantity Pre-fills the Quantity selector on the checkout. data-quantity quantity No
Allow Quantity Enables the quantity selector on the checkout page. (Default: true) data-allow-quantity allowQuantity No
Title Overrides the product’s name on the checkout page. data-title title No
Custom Message A message/string of text displayed under the product name on the checkout. data-message message No
Referrer Adds a custom referrer/campaign string to be stored with the checkout. data-referrer referring_domain No
Disable Logout Disable the ability for a user to logout/change email once on the checkout. data-disable-logout disableLogout No
Upsell The ID of a product you wish to prompt the user to purchase instead. data-upsell upsell No
Upsell Title Customise the title of the upsell dialog. data-upsell-title upsellTitle No
Upsell Text Customise the upsell message displayed to the user. data-upsell-text upsellText No
Upsell Action Customise the upsell button text. data-upsell-action upsellAction No
Checkout Recovery Disable checkout recovery functionality for this checkout. (Default: true) N/A is_recoverable No
Checkout Recovery Auth MD5 hash of the value set for is_recoverable and the “Checkout Secret Key” of the product. (This can be found by clicking on the ‘Checkout Link’ button next to the Product/Subscription in your Paddle Dashboard) N/A is_recoverable_auth Yes (if is_recoverable is also set)

Supported Locales

The following locales are accepted values to be passed with the locale field:

  • en : English
  • de : German
  • fr : French
  • es : Spanish
  • pt : Portuguese
  • nl : Dutch
  • ru : Russian
  • it : Italian
  • ja : Japanese
  • pl : Polish
  • zh-Hans : Chinese Simplified
  • ar : Arabic

Recognised Countries

The following countries are accepted values to be passed with the country field:

  • AF: Afghanistan
  • AL: Albania
  • DZ: Algeria
  • AS: American Samoa
  • AD: Andorra
  • AO: Angola
  • AI: Anguilla
  • AG: Antigua and Barbuda
  • AR: Argentina
  • AM: Armenia
  • AW: Aruba
  • AU: Australia
  • AT: Austria
  • AZ: Azerbaijan
  • BS: Bahamas
  • BH: Bahrain
  • BD: Bangladesh
  • BB: Barbados
  • BY: Belarus
  • BE: Belgium
  • BZ: Belize
  • BJ: Benin
  • BM: Bermuda
  • BT: Bhutan
  • BO: Bolivia
  • BA: Bosnia and Herzegovina
  • BW: Botswana
  • BV: Bouvet Island
  • BR: Brazil
  • IO: Brit. Indian Ocean
  • VG: British Virgin Islands
  • BN: Brunei Darussalam
  • BG: Bulgaria
  • BF: Burkina Faso
  • BI: Burundi
  • KH: Cambodia
  • CM: Cameroon
  • CA: Canada
  • CV: Cape Verde
  • KY: Cayman Islands
  • CF: Central African Republic
  • TD: Chad
  • CL: Chile
  • CN: China
  • CX: Christmas Island
  • CC: Cocos Islands
  • CO: Colombia
  • KM: Comoros
  • CG: Congo
  • CK: Cook Islands
  • CR: Costa Rica
  • CI: Cote D’Ivoire
  • HR: Croatia
  • CU: Cuba
  • CW: Curaçao
  • CY: Cyprus
  • CZ: Czech Republic
  • DK: Denmark
  • DJ: Djibouti
  • DM: Dominica
  • DO: Dominican Republic
  • EC: Ecuador
  • EG: Egypt
  • SV: El Salvador
  • GQ: Equatorial Guinea
  • ER: Eritrea
  • EE: Estonia
  • ET: Ethiopia
  • FK: Falkland Islands
  • FO: Faroe Islands
  • FJ: Fiji
  • FI: Finland
  • FR: France
  • GF: French Guiana
  • PF: French Polynesia
  • TF: French Southern Terr.
  • GA: Gabon
  • GM: Gambia
  • GE: Georgia
  • DE: Germany
  • GH: Ghana
  • GI: Gibraltar
  • GR: Greece
  • GL: Greenland
  • GD: Grenada
  • GP: Guadeloupe
  • GU: Guam
  • GT: Guatemala
  • GG: Guernsey
  • GN: Guinea
  • GW: Guinea-Bissau
  • GY: Guyana
  • HT: Haiti
  • HM: Heard/ Mcdonald Islands
  • VA: Holy See/ Vatican City
  • HN: Honduras
  • HK: Hong Kong
  • HU: Hungary
  • IS: Iceland
  • IN: India
  • ID: Indonesia
  • IR: Iran
  • IQ: Iraq
  • IE: Ireland
  • IL: Israel
  • IT: Italy
  • JM: Jamaica
  • JP: Japan
  • JE: Jersey
  • JO: Jordan
  • KZ: Kazakhstan
  • KE: Kenya
  • KI: Kiribati
  • KW: Kuwait
  • KG: Kyrgyzstan
  • LA: Lao People’s DR
  • LV: Latvia
  • LB: Lebanon
  • LS: Lesotho
  • LR: Liberia
  • LY: Libyan Arab Jamahiriya
  • LI: Liechtenstein
  • LT: Lithuania
  • LU: Luxembourg
  • MO: Macao
  • MK: Macedonia
  • MG: Madagascar
  • MW: Malawi
  • MY: Malaysia
  • MV: Maldives
  • ML: Mali
  • MT: Malta
  • MH: Marshall Islands
  • MQ: Martinique
  • MR: Mauritania
  • MU: Mauritius
  • YT: Mayotte
  • MX: Mexico
  • FM: Micronesia
  • MD: Moldova
  • MC: Monaco
  • MN: Mongolia
  • ME: Montenegro
  • MS: Montserrat
  • MA: Morocco
  • MZ: Mozambique
  • MM: Myanmar
  • NA: Namibia
  • NR: Nauru
  • NP: Nepal
  • NL: Netherlands
  • AN: Netherlands Antilles
  • NC: New Caledonia
  • NZ: New Zealand
  • NI: Nicaragua
  • NE: Niger
  • NG: Nigeria
  • NU: Niue
  • NF: Norfolk Island
  • KP: North Korea
  • MP: Northern Mariana Islands
  • NO: Norway
  • OM: Oman
  • PK: Pakistan
  • PW: Palau
  • PS: Palestinian Territory
  • PA: Panama
  • PG: Papua New Guinea
  • PY: Paraguay
  • PE: Peru
  • PH: Philippines
  • PN: Pitcairn
  • PL: Poland
  • PT: Portugal
  • PR: Puerto Rico
  • QA: Qatar
  • RS: Republic of Serbia
  • RE: Reunion
  • RO: Romania
  • RU: Russian Federation
  • RW: Rwanda
  • GS: S. Georgia/ Sandwich Islands
  • SH: Saint Helena
  • KN: Saint Kitts and Nevis
  • LC: Saint Lucia
  • PM: Saint Pierre and Miquelon
  • VC: Saint Vincent/ Grenadines
  • WS: Samoa
  • SM: San Marino
  • ST: Sao Tome and Principe
  • SA: Saudi Arabia
  • SN: Senegal
  • SC: Seychelles
  • SL: Sierra Leone
  • SG: Singapore
  • SK: Slovakia
  • SI: Slovenia
  • SB: Solomon Islands
  • SO: Somalia
  • ZA: South Africa
  • KR: South Korea
  • ES: Spain
  • LK: Sri Lanka
  • SD: Sudan
  • SR: Suriname
  • SJ: Svalbard and Jan Mayen
  • SZ: Swaziland
  • SE: Sweden
  • CH: Switzerland
  • SY: Syrian Arab Republic
  • TW: Taiwan
  • TJ: Tajikistan
  • TZ: Tanzania
  • TH: Thailand
  • TL: Timor-Leste
  • TG: Togo
  • TK: Tokelau
  • TO: Tonga
  • TT: Trinidad and Tobago
  • TN: Tunisia
  • TR: Turkey
  • TM: Turkmenistan
  • TC: Turks and Caicos Islands
  • TV: Tuvalu
  • VI: U.S. Virgin Islands
  • UG: Uganda
  • UA: Ukraine
  • AE: United Arab Emirates
  • GB: United Kingdom
  • US: United States
  • UM: United States (M.O.I.)
  • UY: Uruguay
  • UZ: Uzbekistan
  • VU: Vanuatu
  • VE: Venezuela
  • VN: Viet Nam
  • WF: Wallis and Futuna
  • EH: Western Sahara
  • YE: Yemen
  • ZM: Zambia
  • ZW: Zimbabwe

Next Steps

Now you've added the start of the checkout flow, we'd recommend looking at localizing your website based on user geography, or one of the other next steps below:
Localized Prices API
Localized prices on your website.
Paddle Audience
Collect user email addresses and build a customer marketing base using Paddle.js
Download Prompts & Buttons
Track downloads with Paddle.js

Questions about Paddle?

If you need any help regarding your Paddle integration, please get in touch with our Customer Success team using the form below.