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:
- Add a default payment link to your checkout 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
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 your seller ID
Then, follow this by calling the Paddle.Setup() method to set your seller ID:
1234561<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
2<script type="text/javascript">
3 Paddle.Setup({
4 seller: 99999 // replace with your Paddle seller ID
5 });
6</script>You can find your seller ID 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:
12345671<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 seller: 99999 // replace with your Paddle seller ID
6 });
7</script>Remove Paddle.Environment.set() entirely when going live.
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.
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.
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 seller ID 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.
Extend your checkout
That's it! Now you've built a checkout, we recommend:
