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:
Use HTML data attributes on your checkout trigger element. The settings you pass apply only to the opened checkout.
Pass
settings
toPaddle.Checkout.open()
. The settings you pass apply only to the opened checkout.Pass
checkout.settings
toPaddle.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:
Display mode for the checkout.
Class name of the <div>
element where the checkout should be rendered.
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.
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 foriframe
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.
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.
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.
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.
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.
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.
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
:
1234567891011121314151617181<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()
.
This example sets the checkout data-theme
to dark
, data-locale
to Spanish (es
), and data-allow-logout
to false
.
123456789101112131415161718191<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>
For a full list of HTML data attributes, see: HTML data attributes