> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
# Quickstart
Open your first Paddle Checkout in five minutes.
---
Paddle.js is a JavaScript library that you include in your frontend to open checkouts, render localized prices, and integrate with Paddle Retain.
This quickstart walks you through including Paddle.js, initializing it with a client-side token, and opening an overlay checkout. It takes about five minutes.
## Before you begin
You need a Paddle account. You can sign up for free:
- [**Sandbox account**](https://sandbox-login.paddle.com/signup) — for testing. No real money is involved.
- [**Live account**](https://login.paddle.com/signup) — for production use. Requires approval before you can process real transactions.
We recommend starting in the sandbox environment.
You'll also need:
- At least one [product and price](https://developer.paddle.com/build/products/create-products-prices.md) in your Paddle account. Note the price ID, starting with `pri_`.
- A domain approved in **Paddle > Checkout > Website approval**, so you can test from a local file. On sandbox accounts, you can use `localhost` as your domain.
## Get a client-side token {% step=true %}
[Client-side tokens](https://developer.paddle.com/paddle-js/about/client-side-tokens.md) authenticate Paddle.js with your Paddle account. They're safe to expose in frontend code.
{% instruction-steps %}
1. Go to **Paddle > Developer tools > Authentication**.
2. Click the **Client-side tokens** tab.
3. Click {% mock-button icon="carbon:add" %}New client-side token.
4. Enter a name, then click Save.
5. Click the button next to the token, then Copy.
{% /instruction-steps %}
{% /dashboard-instructions %}
Sandbox tokens start with `test_`. Live tokens start with `live_`.
## Include Paddle.js {% step=true %}
You can include Paddle.js using a script tag or an npm package.
{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}
Create an HTML file and load Paddle.js from the Paddle CDN in the ``:
```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/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 it where you'll initialize Paddle.js:
```typescript
import { initializePaddle } from "@paddle/paddle-js";
```
The package includes TypeScript definitions for all Paddle.js methods.
{% /tab-item %}
{% /tabs %}
## Initialize Paddle.js {% step=true %}
Initialize Paddle.js with your client-side token. For sandbox tokens, also set the environment to `sandbox`.
{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}
Call [`Paddle.Initialize()`](https://developer.paddle.com/paddle-js/methods/paddle-initialize.md) inside a script tag:
```html
```
Skip `Paddle.Environment.set()` if you're using a live token.
{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}
Call `initializePaddle()` and keep the returned `paddle` instance. You'll use it to open checkouts:
```typescript
import { initializePaddle, type Paddle } from "@paddle/paddle-js";
let paddle: Paddle | undefined;
initializePaddle({
environment: "sandbox",
token: "test_abc123def456ghi789jkl0mn", // replace with your client-side token
}).then((p) => {
paddle = p;
});
```
Omit `environment` if you're using a live token.
{% /tab-item %}
{% /tabs %}
## Open a checkout {% step=true %}
Open a checkout by calling [`Paddle.Checkout.open()`](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open.md) with the price ID you noted earlier.
{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}
Add a button to your HTML that calls `Paddle.Checkout.open()`:
```html
```
{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}
Wire up a button or other event handler to call `Checkout.open()` on the `paddle` instance you initialized:
```typescript
function openCheckout() {
paddle?.Checkout.open({
items: [
{ priceId: "pri_01h1vjes1y163xfj1rh1tkfb65", quantity: 1 },
],
});
}
```
{% /tab-item %}
{% /tabs %}
Load your page in a browser and click the button. An overlay checkout slides in.
## Take a test payment {% step=true %}
Fill in the checkout with these test card details:
| Field | Value |
| :--------------- | :----------------------------------- |
| Email | Any email address |
| Country | Any country |
| Card number | `4242 4242 4242 4242` |
| Name on card | Any name |
| Expiration date | Any future date |
| Security code | `100` |
When you complete checkout, your test payment shows up in **Paddle > Transactions** in the sandbox dashboard.
## Complete example
Drop your client-side token and price ID in and run it.
{% tabs sync="paddlejs-preference" %}
{% tab-item title="Using a script tag" %}
Save this as `checkout.html`, run a local dev server, and open it in a browser:
```html
```
{% /tab-item %}
{% tab-item title="Using a JavaScript package manager" %}
Import and initialize Paddle.js, then wire up a button to open a checkout:
```typescript
import { initializePaddle, type Paddle } from "@paddle/paddle-js";
let paddle: Paddle | undefined;
initializePaddle({
environment: "sandbox",
token: "test_abc123def456ghi789jkl0mn",
}).then((p) => {
paddle = p;
});
function openCheckout() {
paddle?.Checkout.open({
items: [
{ priceId: "pri_01h1vjes1y163xfj1rh1tkfb65", quantity: 1 },
],
});
}
document.querySelector("#buy")?.addEventListener("click", openCheckout);
```
Add a matching button to your page:
```html
```
{% /tab-item %}
{% /tabs %}
## Next steps
You've opened your first Paddle Checkout. These pages cover what to build next:
{% card-group cols=3 %}
{% card title="Build an overlay checkout" url="/build/checkout/build-overlay-checkout" %}
A deeper walkthrough that covers prefilling customer details, handling events, and styling.
{% /card %}
{% card title="Build an inline checkout" url="/build/checkout/build-branded-inline-checkout" %}
Embed the checkout directly in your page instead of opening it as an overlay.
{% /card %}
{% card title="Pass checkout settings" url="/build/checkout/set-up-checkout-default-settings" %}
Customize the theme, locale, and behavior of your checkouts using default settings.
{% /card %}
{% card title="Paddle.js methods" url="/paddle-js/methods" %}
Browse the full method reference for opening, updating, and closing checkouts.
{% /card %}
{% card title="Paddle.js events" url="/paddle-js/events" %}
Listen for events emitted by Paddle.js to react to customer actions and payment status.
{% /card %}
{% card title="Pricing pages" url="/paddle-js/methods/paddle-pricepreview" %}
Use `Paddle.PricePreview()` to render localized prices on your marketing site.
{% /card %}
{% /card-group %}