Build an overlay checkout
Get a step-by-step overview of how to build a complete overlay checkout — including initializing Paddle.js, passing settings and items, and next steps.
Overlay checkout lets you present customers with a checkout overlay to handle all parts of the checkout process.
This tutorial walks through how to set up an overlay checkout using Paddle.js.
Before you begin
Checkout works with products and prices to say what you're billing for, so you'll need to first create products and related prices.
You'll also need to:
- Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link.
- Get your default payment link domain approved, if you're working with the live environment.
Get started
Add an overlay checkout to your website or app in four steps:
Include and initialize Paddle.js
Add Paddle.js to your app or website, so you can securely capture payment information and build subscription billing experiences.
Add an overlay checkout button
Set any element on your page as a trigger for Paddle Checkout.
Make sure that your checkout loads successfully. Take a test payment using sandbox.
Customize your checkout, prefill customer information, and build custom success workflows.
1. Include and initialize Paddle.js
Paddle.js is a lightweight JavaScript library that lets you build rich, integrated subscription billing experiences using Paddle.
Include Paddle.js script
Include Paddle.js by adding this script to the <head> of your checkout page:
11<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>Pass a client-side token
Then, follow this by calling the Paddle.Setup() method and passing a client-side token:
1234561<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
2<script type="text/javascript">
3 Paddle.Setup({
4 token: '7d279f61a3499fed520f7cd8c08' // replace with a client-side token
5 });
6</script>You can create and manage client-side tokens in Paddle > Developer tools > Authentication.
Set environment (optional)
If you're testing with the sandbox, call the Paddle.Environment.set() method to set your environment to sandbox.
For best performance, do this just before calling Paddle.Setup(), like this:
1234567891<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
2<script type="text/javascript">
3 Paddle.Environment.set("sandbox");
4 Paddle.Setup({
5 token: '7d279f61a3499fed520f7cd8c08', // replace with a client-side token
6 pwAuth: '00000000000000000000000000000000', // replace with your Retain API key
7 pwCustomer: { }
8 });
9</script>Remove Paddle.Environment.set() entirely when going live.
2. Add an overlay checkout button
Create checkout button element
Next, set an element on your page as a trigger for your overlay checkout. When clicked, Paddle.js launches the checkout overlay.
Overlay checkout works by presenting an overlay when a button or another element is clicked.
You could use a link (<a> element) with href='#':
11<a href='#'>Buy now</a>Set your element as a trigger
There are two ways to add an overlay checkout trigger:
| HTML data attributes | Paddle.Checkout.open() |
|---|---|
Add paddle_button class to any element. | Use JavaScript to open checkout when an element is clicked. |
| Optionally styles your element as a button. | No styles applied to your element. |
| Recommended for quickly adding checkout functionality. | Recommended where you want greater flexibility. |
| Best for passing few attributes. | Best for passing multiple attributes. |
HTML data attributes are the simplest way to get started.
Turn any element on your page into a Paddle Checkout button. This is especially good when working with a CMS that has limited customization options, or if you're not comfortable with JavaScript.
Add class and pass settings
First, add paddle_button as a class to an element to tell Paddle.js to use it as a trigger for your checkout.
Optionally add adata-theme attribute to style this element as a button. You can choose dark or light for your button theme.
11<a href='#' class='paddle_button' data-theme='light'>Buy Now</a>
data-theme also determines whether your checkout opens in light mode or dark mode.
You can pass other data attributes to set locale, determine whether customers can log out, and redirect to a success page. See: Pass checkout settings
Pass your items
Next, pass data-items and a list of price objects. Each object should contain a priceId and quantity property. priceId should be a Paddle ID of a price entity.
12345678910111213141516171<a
2 href='#'
3 class='paddle_button'
4 data-theme='light'
5 data-items='[
6 {
7 "priceId": "pri_01gs59hve0hrz6nyybj56z04eq",
8 "quantity": 1
9 },
10 {
11 "priceId": "pri_01gs59p7rcxmzab2dm3gfqq00a",
12 "quantity": 1
13 }
14 ]'
15>
16 Buy now
17</a>3. Test your checkout
Open your checkout page in your browser and test. All things being well, Paddle Checkout should open when you click on your checkout button.
If the checkout doesn't appear, check that:
- You added a default payment link to your checkout under Paddle > Checkout > Checkout settings > Default payment link, and that this matches the domain where you're testing. You could use
localhostif you're testing locally. - You included Paddle.js
- You set the correct environment.
- Your client-side token is correct and passed to
Paddle.Setup(). - The Paddle IDs for price entities that you passed are correct.
4. Extend your checkout
That's it! Now you've built a checkout, we recommend:
