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 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, 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 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 setting ‘Price’)
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 setting ‘Trial Days’)
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 setting checkout recovery)

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

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.
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.