Buttons & Checkout

Checkout Buttons, Overlay Checkout

Make sure you've completed Paddle.js Setup before continuing to this step!

Checkout Buttons

By far the most simple way of using the Paddle Checkout is by including a Paddle Checkout Button on your page. These are automatically setup and linked to the Overlay Checkout upon the library loading.

Any element on your page can be made into a button by giving it the class paddle_button.


<a href="#!" class="paddle_button" data-product="12345">Buy Now!</a>

The only required property of a button is data-product to tell Paddle.js which product it should pop open a checkout for on click. By default, the Paddle Checkout Button will be styled green, you can reset the style by adding the property data-theme with the value none.

There are various additional options you can use within your button, and these are described in detail toward the bottom of this page (See: Checkout Properties).

Invoking a Checkout with Javascript

Building a custom checkout flow that’s deeply embedded into your application may mean that utilising a simple checkout button as illustrated above doesn’t give the level of control needed.

In the below example, we invoke the checkout on click, after tying it to a custom element on our page.

Additionally, in our hypothetical application this is part of a user account page, the user is logged in, so we’re passing into the checkout some information to speed up the process for the end user, the users email address (jane@paddle.com), and their ID within our system (1939284), to help us tie the purchases back to their account upon completion.


<button id="js-buy">Upgrade to Pro</button>
<script type="text/javascript">
  document.getElementById('js-buy').addEventListener('click', function() {
      product: 12345,
      passthrough: '{"email": "jane@paddle.com", "user_id": 1939284}'
  }, false);

A full list of properties that the Paddle.Checkout.open() method supports is included toward the bottom of this page (See: Checkout Properties).

Invoking Checkout Buttons After Page Load

Sometimes you may wish to use the standard Paddle Checkout Button implementation (described in ‘Basic Setup’), but wish to load the buttons dynamically after the page has loaded.

Paddle will automatically look for, and instantiate buttons that are present on the initial page load. If you add additional buttons after this, you’ll need to call the Paddle.Button.load() method to run the instantiation on any newly created buttons.

In the below example, we dynamically add a Paddle Checkout Button to our page after page load, and then instantiate it.


<div id="my-page"></div>


<script type="text/javascript">
  var btn = document.createElement('button');
  btn.setAttribute('class', 'paddle_button');
  btn.setAttribute('data-product', 21345);

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