Paddle Billing

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.

Illustration of an overlay checkout. The payment method form is open, with buttons for Apple Pay and PayPal along with the card details form underneath. The items list shows one item for 'Professional plan', with tax and totals underneath. The total overall is $3600, displayed at the top-left of the checkout.

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:

  1. 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.

  2. Add an overlay checkout button

    Set any element on your page as a trigger for Paddle Checkout.

  3. Test your checkout

    Make sure that your checkout loads successfully. Take a test payment using sandbox.

  4. Extend your checkout

    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:

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:

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:

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='#':

Set your element as a trigger

There are two ways to add an overlay checkout trigger:

HTML data
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.

Illustration showing data-theme none, data-theme light, and data-theme dark

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.

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: