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

# Paddle.Initialize()

Use to initialize Paddle.js and Retain. This is required.

---

Use `Paddle.Initialize()` to initialize Paddle.js and set default checkout settings. This is required when working with pricing pages, checkouts, and Retain workflows.

You can use `Paddle.Initialize()` to:

- Authenticate with your Paddle account
- Integrate with Retain
- Pass settings that apply to all checkouts opened on a page
- Create event callbacks

You must call `Paddle.Initialize()` and pass a client-side token to use Paddle Checkout. You can [create and manage client-side tokens](https://developer.paddle.com/paddle-js/client-side-tokens#create-client-side-token.md) in **Paddle > Developer tools > Authentication**.

{% callout type="warning" %}
You can only call `Paddle.Initialize()` once on a page. You'll get an error if you try to call it more than once. Use [`Paddle.Update()`](https://developer.paddle.com/paddle-js/methods/paddle-update.md) to update `pwCustomer` or pass an updated `eventCallback`.
{% /callout %}

You can pass settings for opened checkouts using either [`Paddle.Checkout.open()`](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open.md) or `Paddle.Initialize()`. Settings passed to `Paddle.Initialize()` are [default settings](https://developer.paddle.com/build/checkout/set-up-checkout-default-settings.md), which means they apply to all checkouts opened on a page.

Paddle.js [emits events for key actions](https://developer.paddle.com/paddle-js/events/overview.md) as a customer moves through checkout. You can pass an `eventCallback` to `Paddle.Initialize()` to call a function for every Paddle.js checkout event. This is typically used as part of an [inline checkout integration](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md) for updating on-page elements, like items lists or breadcrumbs.

## Paddle Retain

{% callout type="warning" %}
Paddle Retain only works with live data. While you can initialize Paddle.js with Retain in sandbox accounts, Retain features aren't loaded there.
{% /callout %}

[Paddle.js integrates with Retain](https://developer.paddle.com/concepts/retain/overview.md), so you don't have to include a separate Retain script in your app or website. Client-side tokens for live accounts authenticate with both Paddle Billing and Paddle Retain, so there's no need to pass a separate key for Retain.

To use Retain, pass `pwCustomer` for logged-in customers. You can update `pwCustomer` after initialization using [`Paddle.Update()`](https://developer.paddle.com/paddle-js/methods/paddle-update.md).

## Parameters

```yaml
title: Paddle.Initialize() properties
type: object
properties:
  token:
    type: string
    description:
      Client-side token for authentication. You can create and manage client-side tokens in Paddle > Developer tools >
      Authentication. Required.
  pwCustomer:
    type:
      - object
      - "null"
    description: >-
      Identifier for a logged-in customer for Paddle Retain. Pass an empty object if you don't have a logged-in
      customer. Paddle Retain is only loaded for live accounts.
    properties:
      id:
        type: string
        description: >-
          Paddle ID of a customer entity, prefixed `ctm_`. Only customer IDs are accepted. Don't pass subscription IDs,
          other Paddle IDs, or your own internal identifiers for a customer.
  checkout:
    type:
      - object
      - "null"
    description: Set general checkout settings. Settings here apply to all checkouts opened on the page.
    properties:
      settings:
        type: object
        description: Configured settings.
        properties:
          allowLogout:
            type:
              - boolean
              - "null"
            default: true
            description: Whether the user can change their email once on the checkout.
          allowDiscountRemoval:
            type:
              - boolean
              - "null"
            default: true
            description: Whether the user can remove an applied discount at checkout. Defaults to `true`.
          allowedPaymentMethods:
            type:
              - array
              - "null"
            description: Payment options presented to customers at checkout.
            items:
              type: string
              enum:
                - alipay
                - apple_pay
                - bancontact
                - blik
                - card
                - google_pay
                - ideal
                - kakao_pay
                - mb_way
                - naver_pay
                - payco
                - paypal
                - pix
                - samsung_pay
                - saved_payment_methods
                - south_korea_local_card
                - upi
              x-enum-descriptions:
                alipay:
                  description: Alipay, popular in China.
                apple_pay:
                  description: Apple Pay on a supported Apple device.
                bancontact:
                  description: Bancontact, popular in Belgium.
                blik:
                  description: BLIK, a popular payment method in Poland.
                card:
                  description: Credit or debit card.
                google_pay:
                  description: Google Pay on a supported Android device, Chromebook, or Google Chrome browser.
                ideal:
                  description: iDEAL, popular in the Netherlands.
                kakao_pay:
                  description: Kakao Pay, a popular payment method in Korea.
                mb_way:
                  description: MB WAY, a popular payment method in Portugal.
                naver_pay:
                  description: Naver Pay, a popular payment method in Korea.
                payco:
                  description: Payco, a popular payment method in Korea.
                paypal:
                  description: PayPal.
                pix:
                  description: Pix, popular in Brazil. Available in early access.
                samsung_pay:
                  description: Samsung Pay, a popular payment method in Korea.
                saved_payment_methods:
                  description: >-
                    A customer's existing saved payment methods. Requires `customerAuthToken` to be passed to
                    `Paddle.Checkout.open()`.
                south_korea_local_card:
                  description: Korean local credit or debit card.
                upi:
                  description: Unified Payments Interface (UPI), popular in India. Available in early access.
          displayMode:
            type:
              - string
              - "null"
            default: overlay
            description: Display mode for the checkout.
            enum:
              - inline
              - overlay
            x-enum-descriptions:
              inline:
                description: >-
                  Inline checkout mode. Checkout embedded as a frame in the page. Requires `settings.frameTarget` in
                  `Paddle.Initialize()`.
              overlay:
                description: Overlay checkout mode. Checkout opens in an overlay.
          frameInitialHeight:
            type:
              - string
              - "null"
            examples:
              - "450"
            description: >-
              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:
            type:
              - string
              - "null"
            examples:
              - "min-width: 286px;background-color:transparent;"
            description: >-
              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.
          frameTarget:
            type:
              - string
              - "null"
            examples:
              - checkout-container
            description: Class name of the `<div>` element where the checkout should be rendered.
          locale:
            type:
              - string
              - "null"
            default: (browser default)
            description: Language for the checkout. If omitted, the browser's default locale is used.
            enum:
              - ar
              - zh-Hans
              - zh-TW
              - da
              - nl
              - en
              - fr
              - de
              - it
              - ja
              - ko
              - "no"
              - pl
              - pt
              - pt-BR
              - tr
              - ru
              - es
              - sv
            x-enum-descriptions:
              ar:
                description: Arabic (العربية)
              zh-Hans:
                description: Chinese (Simplified) (简化字)
              zh-TW:
                description: Chinese (Traditional) (正體字)
              da:
                description: Danish (Dansk)
              nl:
                description: Dutch (Nederlands)
              en:
                description: English
              fr:
                description: French (Français)
              de:
                description: German (Deutsch)
              it:
                description: Italian (Italiano)
              ja:
                description: Japanese (日本語)
              ko:
                description: Korean (한국어)
              "no":
                description: Norwegian (Norsk)
              pl:
                description: Polish (Polski)
              pt:
                description: Portuguese (Português)
              pt-BR:
                description: Portuguese (Brazilian) (Português do Brasil)
              tr:
                description: Turkish (Türkçe)
              ru:
                description: Russian (Русский)
              es:
                description: Spanish (Español)
              sv:
                description: Swedish (Svenska)
          showAddDiscounts:
            type:
              - boolean
              - "null"
            default: true
            description: >-
              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. Defaults to `true`.
          showAddTaxId:
            type:
              - boolean
              - "null"
            default: true
            description: Whether the option to add a tax number is displayed at checkout. Defaults to `true`.
          successUrl:
            type:
              - string
              - "null"
            description: URL to redirect to on checkout completion. Must start with `http://` or `https://`.
          theme:
            type:
              - string
              - "null"
            default: light
            description: Theme for the checkout. If omitted, defaults to light.
            enum:
              - light
              - dark
            x-enum-descriptions:
              light:
                description: Light-themed checkout.
              dark:
                description: Dark-themed checkout.
          variant:
            type:
              - string
              - "null"
            default: multi-page
            description: Checkout experience presented to customers. Defaults to `multi-page`.
            enum:
              - one-page
              - multi-page
            x-enum-descriptions:
              one-page:
                description: One-page checkout experience. Customer information and payment details collected on the same page.
              multi-page:
                description: Multi-page checkout experience. Customer information and payment details collected on separate pages.
  eventCallback:
    # The underlying JSON Schema type is object|null (functions are objects in JS)
    # but the docs need to display the TypeScript callable signature instead.
    type:
      - object
      - "null"
    x-display-type: "(event: EventData) => void | null"
    description: Function to call for Paddle.js events.
```

## Examples

{% accordion %}

{% accordion-item title="Initialize Paddle.js" %}

This example passes a client-side token to Paddle.js. This is required.

You can create and manage client-side tokens in **Paddle > Developer tools > Authentication**.

{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}

```js
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08",
});
```

{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}

```ts
import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});
```

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

To learn more, see [Include and initialize Paddle.js](https://developer.paddle.com/paddle-js/include-paddlejs.md)

{% /accordion-item %}

{% accordion-item title="Pass customer ID for Retain" %}

For logged-in users, you should pass `pwCustomer`.

This example passes the Paddle ID for a customer entity in Paddle to Retain.

{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}

```js
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08",
  pwCustomer: {
    id: "ctm_01gt25aq4b2zcfw12szwtjrbdt",
  },
});
```

{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}

```ts
import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  pwCustomer: {
    id: "ctm_01gt25aq4b2zcfw12szwtjrbdt", // replace with a customer Paddle ID
  },
});
```

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

Where you don't know the Paddle ID for a customer, you can pass an empty object to `pwCustomer`.

To learn more, see [Initialize Paddle.js with Retain](https://developer.paddle.com/paddle-js/include-paddlejs#manual-initialize-paddlejs-retain.md)

{% /accordion-item %}

{% accordion-item title="Set default checkout settings (inline)" %}

This example sets default checkout settings for all checkouts opened on a page. It includes common settings for `inline` checkouts.

{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}

```js
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "inline",
      theme: "light",
      locale: "en",
      frameTarget: "checkout-container",
      frameInitialHeight: "450",
      frameStyle:
        "width: 100%; min-width: 312px; background-color: transparent; border: none;",
    },
  },
});
```

{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}

```ts
import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "inline",
      theme: "light",
      locale: "en",
      frameTarget: "checkout-container",
      frameInitialHeight: 450,
      frameStyle:
        "width: 100%; min-width: 312px; background-color: transparent; border: none;",
    },
  },
});
```

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

To learn more, see [Pass checkout settings](https://developer.paddle.com/build/checkout/set-up-checkout-default-settings.md)

{% /accordion-item %}

{% accordion-item title="Set default checkout settings for one-page (inline)" %}

This example sets default checkout settings for all checkouts opened on a page. It includes the required settings to open a one-page inline checkout.

{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}

```js
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "inline",
      variant: "one-page",
      theme: "light",
      locale: "en",
      frameTarget: "checkout-container",
      frameInitialHeight: "450",
      frameStyle:
        "width: 100%; min-width: 312px; background-color: transparent; border: none;",
    },
  },
});
```

{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}

```ts
import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "inline",
      variant: "one-page",
      theme: "light",
      locale: "en",
      frameTarget: "checkout-container",
      frameInitialHeight: 450,
      frameStyle:
        "width: 100%; min-width: 312px; background-color: transparent; border: none;",
    },
  },
});
```

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

{% /accordion-item %}

{% accordion-item title="Set default checkout settings (overlay)" %}

This example sets default checkout settings for all checkouts opened on a page. It includes common settings for `overlay` checkouts.

{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}

```js
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "overlay",
      theme: "light",
      locale: "en",
    },
  },
});
```

{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}

```ts
import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "overlay",
      theme: "light",
      locale: "en",
    },
  },
});
```

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

To learn more, see [Paddle.js events](https://developer.paddle.com/paddle-js/events/overview.md)

{% /accordion-item %}

{% accordion-item title="Log events to console" %}

This example logs events emitted by Paddle.js to console.

{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}

```js
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  eventCallback: function (data) {
    console.log(data);
  },
});
```

{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}

```ts
import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  eventCallback: (data) => {
    console.log(data);
  },
});
```

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

To learn more, see [Paddle.js events](https://developer.paddle.com/paddle-js/events/overview.md)

{% /accordion-item %}

{% accordion-item title="Log text to console based on events emitted" %}

This example uses a switch statement to log some text to console based on events emitted by Paddle.js.

{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}

```js
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  eventCallback: function (data) {
    switch (data.name) {
      case "checkout.loaded":
        console.log("Checkout opened");
        break;
      case "checkout.customer.created":
        console.log("Customer created");
        break;
      case "checkout.completed":
        console.log("Checkout completed");
        break;
      default:
        console.log(data);
    }
  },
});
```

{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}

```ts
import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  eventCallback: (data) => {
    switch (data.name) {
      case "checkout.loaded":
        console.log("Checkout opened");
        break;
      case "checkout.customer.created":
        console.log("Customer created");
        break;
      case "checkout.completed":
        console.log("Checkout completed");
        break;
      default:
        console.log(data);
    }
  },
});
```

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

To learn more, see [Paddle.js events](https://developer.paddle.com/paddle-js/events/overview.md)

{% /accordion-item %}

{% /accordion %}