Paddle Billing
Search

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

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.

The inline checkout footer includes a message to let customers know that Paddle is the merchant of record for the transaction. For compliance, the inline checkout frame must be sized so that the footer message is visible.

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

Early access

One-page inline checkout

By default, Paddle presents customers with a multi-page checkout experience. You can present customers with a one-page experience to collect customer information and payment details on the same page.

Use variant to present one-page or multi-page checkout experiences. Paddle Checkout defaults to one-page by default.

variantstring or null

Checkout experience presented to customers. Defaults to multi-page.

Only valid where displayMode is inline; ignored otherwise.

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.

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.

localestring or null

Language for the checkout.

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.

showAddDiscountsboolean or null

Whether the option to add a discount is displayed at checkout. Defaults to true.

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.

showAddTaxIdboolean or null

Whether the option to add a tax number is displayed at checkout. Defaults to true.

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:

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

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