Pass checkout settings

As well as passing items to a checkout, you can pass settings that tell Paddle.js how a checkout should work.

If you sell multiple products or plans, you might have more than one checkout button on a page. To save time, you can pass default settings that apply to all checkouts opened when including Paddle.js.

How it works

You can pass settings to Paddle.js to determine how opened checkouts should work.

There are three ways to do this:

1. Use HTML data attributes on your checkout trigger element. The settings you pass apply only to the opened checkout.

2. Pass settings to Paddle.Checkout.open(). The settings you pass apply only to the opened checkout.

3. Pass checkout.settings to Paddle.Initialize(). The settings you pass apply to all checkouts.

If you have more than one checkout link on a page and all the checkouts you use have the same settings, we recommend using the Paddle.Initialize() method. This sets default settings that apply to all checkouts opened on the page, meaning you don't need to pass the same settings for each checkout.

Use Paddle.Checkout.open() or HTML data attributes to pass settings for each checkout on a page. HTML data attributes are generally recommended for overlay checkouts, or when working with a CMS that has limited customization options.

Before you begin

You'll need to include Paddle.js on your page and pass a client-side token and Retain API key.

To open a checkout, you'll need to create products and prices and pass them to a checkout.

Get a step-by-step overview of how to build a complete checkout — including passing checkout settings. See: Build an overlay checkout or build an inline checkout

Required settings

If you're building an inline checkout, some settings are required:

frameStyle isn't required, but strongly recommended for styling the inline checkout frame. If not set, checkout frames inherit browser or default styles for iframe elements.

Recommended settings

Dark mode

Use theme to style a checkout for dark or light mode. Paddle Checkout defaults to light by default.

Allow logout

If you're presenting an existing customer with options to upgrade, set allowLogout to false. This hides the option to change the customer on an opened checkout.

Locale

Paddle Checkout uses the browser default locale if locale isn't passed. If you have a langauge selector on your website or app, we recommend passing the chosen locale to opened checkout so that it matches.

Hide option to add discount

Paddle Checkout includes an "Add Discount" option to let customers enter a discount code. If you don't offer discounts, you might like to hide this option.

Hide option to add tax number

Paddle Checkout includes an "Add tax number" option to let customers enter a tax number and business information. If you don't work with businesses, you might like to hide this option.

Set default settings using Paddle.Initialize()

Rather than passing checkout settings each time you create a link or call Paddle.Checkout.open, you can set default settings when you include Paddle.js. These settings apply to all checkouts opened on the page.

Use the Paddle.Initialize() method and pass your checkout defaults to checkout.settings. You can do this in the same block where you include Paddle.js on your page.

This example sets up an inline checkout, then sets the checkout theme to dark, locale to Spanish (es), and allowLogout to false:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
1<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
2<script type="text/javascript">
3  Paddle.Initialize({
4    token: 'live_7d279f61a3499fed520f7cd8c08', // replace with a client-side token
5    pwCustomer: { },
6    checkout: {
7      settings: {
8        displayMode: "inline",
9        frameTarget: "checkout-container"
10        frameInitialHeight: "450",
11        frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
12        theme: "dark",
13        locale: "es",
14        allowLogout: false
15      }
16    } 
17  });
18</script>

See: Paddle.Initialize()

Pass settings for each checkout

You can pass settings for each checkout that you open on the page when you create a link or call Paddle.Checkout.open().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
1<a 
2  href='#' 
3  class='paddle_button'
4  data-theme='dark'
5  data-locale='es'
6  data-allow-logout='false'
7  data-items='[
8    {
9      "priceId": "pri_01gs59hve0hrz6nyybj56z04eq",
10      "quantity": 1
11    },
12    {
13      "priceId": "pri_01gs59p7rcxmzab2dm3gfqq00a",
14      "quantity": 1
15    }
16  ]'
17>
18  Buy Now
19</a>

Related pages