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.
Never use API keys with Paddle.js. API keys should be kept secret and never used in your frontend. Revoke keys immediately if they've been used in your frontend.
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:
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>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.
Install Paddle.js using your package manager:
pnpm add @paddle/paddle-jsyarn add @paddle/paddle-jsnpm install @paddle/paddle-jsThen import into your project:
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:
<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:
import { initializePaddle } from "@paddle/paddle-js";
const paddle = await initializePaddle({ token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token});Set up Retain Optional
Paddle Retain only works on live accounts
Paddle Retain only works with live data. While you can initialize Paddle.js with Retain in sandbox accounts, Retain features aren't loaded there.
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.
<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>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 },});