Paddle Billing


Initializes Paddle.js and Retain. Replaces Paddle.Setup().

Use Paddle.Initialize() to initialize Paddle.js and set default checkout settings. This is a required method, letting you:

  • 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 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() to update pwCustomer or pass an updated eventCallback.

You can pass settings for opened checkouts using either or Paddle.Initialize(). Settings passed to Paddle.Initialize() are default settings, applied 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.Initialize() replaces the deprecated Paddle.Setup() method. It's functionally the same.

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 use either a Paddle ID of a customer entity or an email address. You can update pwCustomer after initialization using Paddle.Update().

Only available for live accounts. Paddle Retain works with live data only, meaning this method is only available for live accounts. Paddle Retain is not loaded at all for sandbox accounts.



Client-side token for authentication. You can create and manage client-side tokens in Paddle > Developer tools > Authentication. Required.

pwCustomerobject or null

Identifier for a logged-in customer for Paddle Retain. Pass either id or email, or an empty object if you don't have a logged-in customer. Paddle Retain is only loaded for live accounts.

idstring or null

Paddle ID for a customer entity in Paddle. Do not pass a subscription ID.

emailstring<email> or null

Email address related to a customer entity in Paddle.

checkoutobject or null

Set general checkout settings. Settings here apply to all checkouts opened on the page.

eventCallback(event: EventData) => void or null

Function to call for Paddle.js events.


Related pages