Docs

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.

Include Paddle.js using a script tag or an npm package, then initialize it with a client-side token.

You should include and initialize Paddle.js on pages where you open a pricing page or a checkout.

Before you begin

You need a client-side token to authenticate with Paddle.js.

Create a token in Paddle > Developer tools > Authentication, using the Paddle API, or using the Paddle MCP server.

Use an AI agent

Include Paddle.js

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

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

HTML
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>

Install Paddle.js using your package manager:

pnpm
pnpm add @paddle/paddle-js
yarn
yarn add @paddle/paddle-js
npm
npm install @paddle/paddle-js

Then import into your project:

TypeScript
import { initializePaddle } from '@paddle/paddle-js';

The package includes TypeScript definitions for all Paddle.js methods.

Initialize and authenticate

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

HTML
<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
  });
</script>

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

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


const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
});

Set up Retain Optional

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.

Where to initialize Paddle.js for Retain

As well as pricing pages and checkouts, you should also initialize Paddle.js on:

  • Public-facing pages 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.
  • 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 pages

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

In-app authenticated pages

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

HTML
<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: {
      id: "ctm_01gt25aq4b2zcfw12szwtjrbdt", // replace with a customer Paddle ID
    },
  });
</script>
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
  },
});

Was this page helpful?