Include and initialize Paddle.js

Include Paddle.js on your website to start building checkout experiences with Paddle. Initialize and authenticate by passing a client-side token.

You can manually load the Paddle.js script on your website using a script tag.

Add the script tag to your HTML

Add the Paddle.js script to the <head> section of your HTML:

Always load Paddle.js directly from https://cdn.paddle.com/. This makes sure that you're running with the latest security and feature updates from Paddle.

Initialize and authenticate

You need a client-side token to authenticate with Paddle.js. Create a token in Paddle > Developer tools > Authentication.

Never use API keys with Paddle.js. API keys should be kept secret and away from the frontend. Revoke the key if it has been compromised. Use client-side tokens starting with test_ or live_.

Initialize Paddle.js by calling the Paddle.Initialize() method with a configuration object that includes a client-side token as the token property:

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

You should initialize Paddle.js in the following places to take full advantage of Retain:

  1. Public-facing page

    Retain emails link back to your site, so customers can complete or confirm actions. Initialize Paddle.js on a public-facing marketing page that Retain can redirect to, like your homepage or pricing page.

  2. In-app authenticated pages

    Initialize Paddle.js on logged-in, authenticated pages so Retain can send in-app payment recovery and term optimization notifications, and display in-app cancellation flows.

Public-facing site

For public-facing pages, you can use the standard initialization script from the previous step without any extra configuration.

In-app authenticated pages

You need to include a pwCustomer object in the configuration object passed to the Paddle.Initialize() method. The id property of the pwCustomer object must be the Paddle ID of a customer entity. Other IDs and internal identifiers for a customer don't work with Retain.

pwCustomerobject or 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.

Only available for live accounts.

Paddle Retain runs on live data. While you can initialize Paddle.js with Retain in sandbox accounts, Retain features aren't loaded there.

Related pages