> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
# 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](https://developer.paddle.com/paddle-js/client-side-tokens.md) to authenticate with Paddle.js.
[Create a token](https://developer.paddle.com/paddle-js/client-side-tokens#create-client-side-token.md) in **Paddle > Developer tools > Authentication**, using the Paddle API, or using the Paddle MCP server.
{% callout type="danger" %}
Never use [API keys](https://developer.paddle.com/api-reference/about/api-keys#format.md) with Paddle.js. API keys should be kept secret and never used in your frontend. [Revoke keys](https://developer.paddle.com/api-reference/about/api-keys#revoke-api-key.md) immediately if they've been used in your frontend.
{% /callout %}
## Use an AI agent
## Include Paddle.js {% step=true %}
{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}
You can manually load the Paddle.js script on your website using a script tag.
Add the Paddle.js script to the `` section of your HTML:
```html
```
{% callout type="warning" %}
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.
{% /callout %}
{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}
Install Paddle.js using your package manager:
{% code-group sync="js-package-manager" %}
```bash {% title="pnpm" %}
pnpm add @paddle/paddle-js
```
```bash {% title="yarn" %}
yarn add @paddle/paddle-js
```
```bash {% title="npm" %}
npm install @paddle/paddle-js
```
{% /code-group %}
Then import into your project:
```typescript
import { initializePaddle } from '@paddle/paddle-js';
```
The package includes TypeScript definitions for all Paddle.js methods.
{% /tab-item %}
{% /tabs %}
## Initialize and authenticate {% step=true %}
{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}
Initialize Paddle.js by calling the [`Paddle.Initialize()`](https://developer.paddle.com/paddle-js/methods/paddle-initialize.md) method with a configuration object that includes a client-side token as the `token` property:
```html
```
{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}
Initialize Paddle.js by calling the [`initializePaddle()`](https://github.com/PaddleHQ/paddle-js-wrapper?tab=readme-ov-file#initialize-paddlejs) function with a configuration object that includes a client-side token as the `token` property:
```ts
import { initializePaddle } from "@paddle/paddle-js";
const paddle = await initializePaddle({
token: "live_7d279f61a3499fed520f7cd8c08", // replace with a client-side token
});
```
{% /tab-item %}
{% /tabs %}
## Set up Retain {% step=true badge="Optional" %}
{% callout type="warning" %}
Paddle Retain only works with live data. While you can initialize Paddle.js with Retain in sandbox accounts, Retain features aren't loaded there.
{% /callout %}
[Paddle.js integrates with Retain](https://developer.paddle.com/concepts/retain/overview.md), so you don't have to include a separate Retain script in your app or website.
[Client-side tokens](https://developer.paddle.com/paddle-js/client-side-tokens.md) 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](https://developer.paddle.com/build/retain/configure-payment-recovery-dunning.md) and [term optimization](https://developer.paddle.com/build/retain/configure-term-optimization-automatic-upgrades.md) notifications, and display in-app [cancellation flows](https://developer.paddle.com/build/retain/configure-cancellation-flows-surveys.md).
### 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](https://developer.paddle.com/paddle-js/methods/paddle-initialize.md). The `id` property of the `pwCustomer` object must be the Paddle ID of a [customer entity](https://developer.paddle.com/api-reference/customers/overview.md). Other IDs and internal identifiers for a customer don't work with Retain.
{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}
```html
```
{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}
```ts
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
},
});
```
{% /tab-item %}
{% /tabs %}