> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# 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](https://developer.paddle.com/paddlejs/overview.md) 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. You can do this in three ways:

- **Pass data attributes to button that opens checkout.**  
   Use [HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes.md) on your checkout launcher element. The settings you pass apply only to the opened checkout.
- **Apply settings to only the opened checkout.**  
   Pass `settings` to [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md). The settings you pass apply only to the opened checkout.
- **Apply settings to all checkouts opened on a page.**  
   Pass `checkout.settings` to [`Paddle.Initialize()`](https://developer.paddle.com/paddlejs/methods/paddle-initialize.md). 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](https://developer.paddle.com/build/checkout/build-overlay-checkout.md), or when working with a CMS that has limited customization options.

## Before you begin

- [Include Paddle.js on your page](https://developer.paddle.com/paddlejs/include-paddlejs.md) and pass a [client-side token](https://developer.paddle.com/paddlejs/client-side-tokens.md).
- To open a checkout, you'll need to [create products and prices](https://developer.paddle.com/build/products/create-products-prices.md) and [pass them to a checkout](https://developer.paddle.com/build/checkout/pass-update-checkout-items.md).

{% callout type="note" %}
To get a step-by-step overview of how to build a complete checkout, including passing checkout settings and prefilling properties, see [Build an overlay checkout](https://developer.paddle.com/build/checkout/build-overlay-checkout.md) or [build an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md)
{% /callout %}

## Required settings

If you're building [an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md), some settings are required:

- **displayMode** (string|null): Display mode for the checkout.. Default: `overlay`
- **frameTarget** (string|null): Class name of the element where the checkout should be rendered.
- **frameStyle** (string|null): Styles to apply to the checkout element. `min-width` must be set to `286px` or above with checkout padding off, `312px` with checkout padding on.
- **frameInitialHeight** (string|null): Height in pixels of the `<div>` on load. Do not include `px`. Recommended `450`.

{% callout type="info" %}
`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.
{% /callout %}

## Recommended settings

### One-page 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 `multi-page` by default.

- **variant** (string|null): Checkout experience presented to customers.. Default: `multi-page`

### Dark mode

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

- **theme** (string|null): Theme for the checkout.. Default: `light`

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

- **allowLogout** (boolean|null): Whether the user can change their email once on the checkout.. Default: `true`

{% callout type="info" %}
When you pass a `customerAuthToken` to Paddle.js to authenticate a customer, or you pass an `upsell` object to Paddle.js to  [show an upsell flow](https://developer.paddle.com/build/checkout/upsell-checkout.md), `allowLogout` is ignored and set to `false`.
{% /callout %}

### Locale

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

- **locale** (string|null): Language for the checkout. If omitted, the browser's default locale is used.. Default: `(browser default)`

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

- **showAddDiscounts** (boolean|null): Whether the option to add a discount is displayed at checkout. Requires the "display discount field on the checkout" option enabled in Paddle > Checkout > Checkout settings.. Default: `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.

- **showAddTaxId** (boolean|null): Whether the option to add a tax number is displayed at checkout.. Default: `true`

## Set default settings during initialization

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](https://developer.paddle.com/paddlejs/include-paddlejs.md) 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`:

```html {% highlightLines="12-14" %}
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
<script type="text/javascript">
  Paddle.Initialize({
    token: 'live_7d279f61a3499fed520f7cd8c08', // replace with a client-side token
    pwCustomer: { },
    checkout: {
      settings: {
        displayMode: "inline",
        frameTarget: "checkout-container"
        frameInitialHeight: "450",
        frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
        theme: "dark",
        locale: "es",
        allowLogout: false
      }
    } 
  });
</script>
```

To learn more, see [`Paddle.Initialize()`](https://developer.paddle.com/paddlejs/methods/paddle-initialize.md)

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

{% tabs sync="js-html-implementation" %}
{% tab-item title="JavaScript properties" %}

This example sets the checkout `theme` to `dark`, `locale` to Spanish (`es`), and `allowLogout` to `false`.

```javascript {% highlightLines="[3,4,5]" %}
Paddle.Checkout.open({
  settings: {
    theme: "dark",
    locale: "es",
    allowLogout: false,
    items: [
      {
        priceId: 'pri_01gs59hve0hrz6nyybj56z04eq',
        quantity: 1
      },
      {
        priceId: 'pri_01gs59p7rcxmzab2dm3gfqq00a',
        quantity: 1
      }
    ]
  }
});
```

For a full list of parameters, see [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md)

{% /tab-item %}
{% tab-item title="HTML data attributes" %}

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

```html {% title="Paddle Checkout launcher" highlightLines="4-6" %}
<a 
  href='#' 
  class='paddle_button'
  data-theme='dark'
  data-locale='es'
  data-allow-logout='false'
  data-items='[
    {
      "priceId": "pri_01gs59hve0hrz6nyybj56z04eq",
      "quantity": 1
    },
    {
      "priceId": "pri_01gs59p7rcxmzab2dm3gfqq00a",
      "quantity": 1
    }
  ]'
>
  Buy Now
</a>
```

For a full list of HTML data attributes, see [HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes.md)

{% /tab-item %}
{% /tabs %}