Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing

Pass checkout settings

Pass settings to Paddle.js to determine how opened checkouts should work. Set default settings for all checkouts on a page to save time.

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.Setup(). 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.Setup() 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 your seller ID 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:

displayModestring or null

Display mode for the checkout.

frameTargetstring or null

Class name of the <div> element where the checkout should be rendered.

frameStylestring<css> or null

Styles to apply to the checkout <div>. min-width must be set to 286px or above with checkout padding off; 312px with checkout padding on. Use frameInitialHeight to set height.

frameInitialHeightstring or null

Height in pixels of the <div> on load. Do not include px. Recommended 450.

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.

themestring or null

Theme for the checkout.

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.

allowLogoutboolean or null

Whether the user can change their email once on the checkout.


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.

localestring or null

Language for the checkout.

Set default settings using Paddle.Setup()

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.Setup() 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:

See: Paddle.Setup()

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.

This example sets the checkout data-theme to dark, data-locale to Spanish (es), and data-allow-logout to false.

For a full list of HTML data attributes, see: HTML data attributes

Related pages