Docs

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 in Paddle > Developer tools > Authentication.

You can pass settings for opened checkouts using either Paddle.Checkout.open() or Paddle.Initialize(). Settings passed to Paddle.Initialize() are default settings, which means they apply to all checkouts opened on a page.

Paddle.js emits events for key actions 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 for updating on-page elements, like items lists or breadcrumbs.

Paddle Retain

Paddle.js integrates with Retain, 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().

Parameters

tokenstring
Client-side token for authentication. You can create and manage client-side tokens in Paddle > Developer tools > Authentication. Required.
pwCustomerobject | null
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.
idstring
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.
checkoutobject | null
Set general checkout settings. Settings here apply to all checkouts opened on the page.
settingsobject
Configured settings.
allowLogoutboolean | null
Default: true
Whether the user can change their email once on the checkout.
allowDiscountRemovalboolean | null
Default: true
Whether the user can remove an applied discount at checkout. Defaults to true.
allowedPaymentMethodsarray | null
Payment options presented to customers at checkout.
Values
  • alipay
    Alipay, popular in China.
  • apple_pay
    Apple Pay on a supported Apple device.
  • bancontact
    Bancontact, popular in Belgium.
  • blik
    BLIK, a popular payment method in Poland.
  • card
    Credit or debit card.
+ Show all values
  • google_pay
    Google Pay on a supported Android device, Chromebook, or Google Chrome browser.
  • ideal
    iDEAL, popular in the Netherlands.
  • kakao_pay
    Kakao Pay, a popular payment method in Korea.
  • mb_way
    MB WAY, a popular payment method in Portugal.
  • naver_pay
    Naver Pay, a popular payment method in Korea.
  • payco
    Payco, a popular payment method in Korea.
  • paypal
    PayPal.
  • pix
    Pix, popular in Brazil. Available in early access.
  • samsung_pay
    Samsung Pay, a popular payment method in Korea.
  • saved_payment_methods
    A customer's existing saved payment methods. Requires customerAuthToken to be passed to Paddle.Checkout.open().
  • south_korea_local_card
    Korean local credit or debit card.
  • upi
    Unified Payments Interface (UPI), popular in India. Available in early access.
displayModestring | null
Default: overlay
Display mode for the checkout.
Values
  • inline
    Inline checkout mode. Checkout embedded as a frame in the page. Requires settings.frameTarget in Paddle.Initialize().
  • overlay
    Overlay checkout mode. Checkout opens in an overlay.
frameInitialHeightstring | null
Example: 450

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.

frameStylestring | null
Example: min-width: 286px;background-color:transparent;
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.
frameTargetstring | null
Example: checkout-container
Class name of the <div> element where the checkout should be rendered.
localestring | null
Default: (browser default)
Language for the checkout. If omitted, the browser's default locale is used.
Values
  • ar
    Arabic (العربية)
  • zh-Hans
    Chinese (Simplified) (简化字)
  • zh-TW
    Chinese (Traditional) (正體字)
  • da
    Danish (Dansk)
  • nl
    Dutch (Nederlands)
+ Show all values
  • en
    English
  • fr
    French (Français)
  • de
    German (Deutsch)
  • it
    Italian (Italiano)
  • ja
    Japanese (日本語)
  • ko
    Korean (한국어)
  • no
    Norwegian (Norsk)
  • pl
    Polish (Polski)
  • pt
    Portuguese (Português)
  • pt-BR
    Portuguese (Brazilian) (Português do Brasil)
  • tr
    Turkish (Türkçe)
  • ru
    Russian (Русский)
  • es
    Spanish (Español)
  • sv
    Swedish (Svenska)
showAddDiscountsboolean | null
Default: true
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.
showAddTaxIdboolean | null
Default: true
Whether the option to add a tax number is displayed at checkout. Defaults to true.
successUrlstring | null
URL to redirect to on checkout completion. Must start with http:// or https://.
themestring | null
Default: light
Theme for the checkout. If omitted, defaults to light.
Values
  • light
    Light-themed checkout.
  • dark
    Dark-themed checkout.
variantstring | null
Default: multi-page
Checkout experience presented to customers. Defaults to multi-page.
Values
  • one-page
    One-page checkout experience. Customer information and payment details collected on the same page.
  • multi-page
    Multi-page checkout experience. Customer information and payment details collected on separate pages.
eventCallback(event: EventData) => void | null
Function to call for Paddle.js events.

Examples

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.

JavaScript
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08",
});
TypeScript
import { initializePaddle } from "@paddle/paddle-js";


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

To learn more, see Include and initialize Paddle.js

For logged-in users, you should pass pwCustomer.

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

JavaScript
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08",
  pwCustomer: {
    id: "ctm_01gt25aq4b2zcfw12szwtjrbdt",
  },
});
TypeScript
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
  },
});

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

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

JavaScript
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;",
    },
  },
});
TypeScript
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;",
    },
  },
});

To learn more, see Pass checkout settings

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.

JavaScript
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;",
    },
  },
});
TypeScript
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;",
    },
  },
});

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

JavaScript
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "overlay",
      theme: "light",
      locale: "en",
    },
  },
});
TypeScript
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",
    },
  },
});

To learn more, see Paddle.js events

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

JavaScript
Paddle.Initialize({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
  eventCallback: function (data) {
    console.log(data);
  },
});
TypeScript
import { initializePaddle } from "@paddle/paddle-js";


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

To learn more, see Paddle.js events

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

JavaScript
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);
    }
  },
});
TypeScript
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);
    }
  },
});

To learn more, see Paddle.js events

Was this page helpful?