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, prefilling customer information, and next steps.

The checkout is where customers make purchases. For SaaS businesses, it's the process where customers enter their details and payment information, and confirm that they'd like to sign up for a subscription with you.

You can use Paddle.js to quickly add an overlay checkout into your app. Overlay checkout lets you present customers with an overlay that handles all parts of the checkout process — minimal frontend coding required.

Grab the code and test using CodePen

CodePen is a platform for building and sharing frontend code. Explore the code for this tutorial and test right away using our overlay checkout pen.

What are we building?

In this tutorial, we'll launch an overlay checkout for two items in our product catalog, then we'll extend it by passing customer information.

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.

We'll learn how to:

  • Include and set up Paddle.js using a client-side token
  • Pass items to overlay checkout using or HTML data attributes
  • Take a test payment
  • Prefill customer information using or HTML data attributes

If you like, you can copy-paste the sample code in your editor or view on CodePen and follow along.

Before you begin

Choose a type of checkout

This tutorial walks through creating an overlay checkout. You can also create inline checkouts, which lets you build Paddle Checkout right into your app or website.

We recommend building an overlay checkout if you're new to Paddle. Inline checkouts use the same JavaScript methods as overlay checkouts, so you can switch to an inline checkout later.

Create products and prices

Paddle Checkout works with products and prices to say what you're billing for, so you'll need to create a product and at least one related price to pass to your checkout.

Set your default payment link

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. Take a test payment

    Make sure that your checkout loads successfully, then take a test payment.

  4. Prefill customer information — optional

    Extend your checkout by prefilling customer and address information.

1. Include and initialize Paddle.js

Paddle.js is a lightweight JavaScript library that lets you build rich, integrated subscription billing experiences using Paddle. We can use Paddle.js to securely work with products and prices in our Paddle system, as well as opening checkouts and capturing payment information.

Include Paddle.js script

Start with a blank webpage, or an existing page on your website. Then, include Paddle.js by adding this script to the <head>:

Set environment (optional)

We recommend signing up for a sandbox account to test and build your integration, then switching to a live account later when you're ready to go live.

If you're testing with the sandbox, call Paddle.Environment.set() and set your environment to sandbox:

Pass a client-side token

Next, go to Paddle > Developer tools > Authentication and generate a client-side token. Client-side tokens let you interact with the Paddle platform in frontend code, like webpages or mobile apps. They have limited access to the data in your system, so they're safe to publish.

In your page, call Paddle.Initialize() and pass your client-side token as token. For best performance, do this just after calling Paddle.Environment.set(), like this:

Client-side tokens are separate for your sandbox and live accounts. You'll need to generate a new client-side token for your live account. Sandbox tokens start with test_ to make them easy to distinguish.

2. Add an overlay checkout button

Next, we'll set an element on our page as a trigger for our overlay checkout. Overlay checkout works by presenting an overlay to handle the entire checkout process. When our button or other trigger element is clicked, Paddle.js launches a checkout for us.

Create checkout button element

Any element can be a trigger for an overlay checkout. In our sample, we're using a link (<a>) that points to #. This means it doesn't open a new page.

Set as a checkout trigger

Next, we'll make our checkout element open an overlay checkout by making it a trigger.

There are two ways we can do this: method

Code illustration showing an openCheckout() function. It's cut off, so you can't make out the full code.

  • Works using JavaScript to open a checkout when an element is clicked.
  • You can pass items and settings as parameters to
  • Recommended in most cases.
  • No styles applied to your element.
  • Best for passing multiple attributes.

HTML data attributes

Code illustration showing HTML data attributes added to an a element. It's cut off, so you can't make out the full code.

  • Works by adding a paddle_button class to an element, which Paddle.js turns into a checkout trigger.
  • You can pass items and settings as data attributes against the element.
  • Recommended when you can't use JavaScript.
  • Optionally styles your element to look like a button.
  • Best for passing few attributes.

In general, we recommend using the method, but you can choose the option that makes the most sense for you.

Paddle.js comes with the method, which lets you open a checkout with settings, items, and customer information.

In our sample, we've created a function called openCheckout() to open a checkout. Here's how it works:

  1. We create a variable called itemsList and pass an array of objects, where each object contains a priceId and quantity.

  2. We create a function called openCheckout() that takes a parameter called items.

  3. In our openCheckout() function, we call, passing the value of items as the items list for the checkout.

  4. We add an onclick event to our checkout button to call openCheckout() when clicked, passing our itemsList variable as a parameter.

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.

3. Take a test payment

We're now ready to test! Save your page, then open it in your browser. Click on your "Sign up now" button and Paddle.js should open an overlay checkout for the items that we passed.

If you're using the sandbox environment, you can take a test payment using our test card details:

Email addressAn email address you own
CountryAny valid country supported by Paddle
ZIP code (if required)Any valid ZIP or postal code
Card number4242 4242 4242 4242
Name on cardAny name
Expiration dateAny valid date in the future.
Security code100

Short animation showing launching an overlay checkout, entering contact information, and entering test payment details.

4. Prefill customer information (optional)

So far, we've passed items to our checkout. When we click our trigger, Paddle opens a checkout for the items that we passed.

Paddle.js also lets you pass customer information to a checkout. When we click our trigger, Paddle opens a checkout with the customer information prefilled. This means the first page of checkout is skipped entirely, so customers land on a screen where they can enter their payment information. takes a customer parameter, which lets you pass customer and address information.

In our sample, we've extended our openCheckout() function so that it passes customer and address information to our checkout. Here's what's going on:

  1. We create a variable called customerInfo, with an email key and an object for address. You may also pass Paddle IDs for an existing customer or address here.

  2. We update our openCheckout() function so it takes another parameter called customer.

  3. In our openCheckout() function, we added the customer parameter and passing the value of customer to this.

  4. We updated the onClick event on our checkout button to pass our customerInfo variable as the parameter for customer.

Test your work

Save your page, then open it in your browser. Click on your "Sign up now" button and Paddle.js should open an overlay checkout with the customer information prefilled. You should land on the second screen, ready to enter payment information.

Short animation showing overlay checkout landing on a screen asking for card details.

Next steps

That's it! Now you've built a checkout, you might like to extend Paddle Checkout by automatically applying a discount, passing optional checkout settings, or building a success workflow.

Automatically apply a discount

Extend your checkout by passing a discount. When we click our trigger, Paddle opens a checkout with the discount automatically applied (where it's valid).

Pass checkout settings

You don't need to pass checkout settings when working with overlay checkout, but you can use them to give you more control over how opened checkouts work. For example, you can set the language that Paddle Checkout uses, hide the option to add a discount, or restrict payment methods shown to customers.

Build a success workflow

When customers complete checkout, Paddle Checkout has a final screen that lets customers know that their purchase was successful. If you like, you can redirect customers to your own page or use JavaScript event callbacks to build a more advanced success workflow.