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.
Looking for a tighter integration? Consider inline checkout
For a more integrated experience, consider inline checkout. It lets you build Paddle checkout right into your app or website, so it requires more engineering resource.
Learn more about the differences between overlay and inline checkouts
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.
We recommend starting the domain approval early in your integration process, so your domains are approved for when you're ready to go-live.
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>
To use Retain, include Paddle.js on every page of your web app or website — including your commercial or marketing website.
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
To speed up checkout, you can also prefill customer information and other information. Pass all required properties to create a one-page checkout. See: Prefill checkout properties
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.
API
List prices by making a GET request to the /prices
endpoint. Work your way through the results to find the price that you'd like to work with.
Dashboard
Head to Paddle > Catalog > Products, click on a product in the list, then click the … menu next to a price and choose Copy ID.
Recurring items on a checkout must have the same billing interval. For example, you can't have a checkout with some prices that are billed monthly and some products that are billed annually.
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>
Use single quotation marks around the value of
data-items
, and double quotation marks around the property names and string values inside it.
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
localhost
if 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.
Your sandbox and live systems are separate. Check that you're using the correct price IDs for the environment that you're working in.
4. Extend your checkout
That's it! Now you've built a checkout, we recommend:
- Build an overlay checkout
- Before you begin
- Get started
- 1. Include and initialize Paddle.js
- Include Paddle.js script
- Pass a client-side token
- Set environment (optional)
- 2. Add an overlay checkout button
- Create checkout button element
- Set your element as a trigger
- 3. Test your checkout
- 4. Extend your checkout