Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing

Build an inline checkout

Get a step-by-step overview of how to build a complete inline checkout — including initializing Paddle.js, passing settings and items, and next steps.

Inline checkout lets you create checkout experiences that are integrated with your app or website.

This tutorial walks through how to set up an inline checkout using Paddle.js.

Illustration showing an inline checkout implementation. The Paddle Checkout frame is on the left and is on the payment page. It shows buttons for Apple Pay and PayPal, followed by a card payment form. On the right is an items list and totals. The grand total is $3600 billed monthly and is at the top.

New to Paddle? Consider overlay checkout

Inline checkout integrates into your app or website, so it requires knowledge of HTML, CSS, and JavaScript to implement. Consider overlay checkout if you're just getting started.

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

Build an inline checkout in six 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:

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:

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:

Remove Paddle.Environment.set() entirely when going live.

Embed and pass checkout settings

Create checkout container

Next, create an empty <div> for the Paddle Checkout frame and give it a unique class.

Inline checkout works by embedding a frame with Paddle Checkout into your website or app. We'll pass the class of this empty <div> later to tell Paddle.js where to embed the checkout frame.

Pass settings

Then, pass settings to your checkout to tell Paddle.js how your checkout should work.

There are two ways to do this:

  1. Pass settings to Paddle.Checkout.open(). The settings you pass apply only to the opened checkout.

  2. Pass checkout.settings to Paddle.Setup(). The settings you pass apply to all checkouts, meaning you don't need to set them each time.

If all the checkouts you use have the same settings, we recommend using the Paddle.Setup() method. This means you don't need to pass the same settings for every checkout that you'd like to open.

In these examples:

  • displayMode is set to inline to tell Paddle.js to render an inline checkout.
  • frameTarget is set to our empty checkout element.
  • frameInitialHeight is set to 450.

We also use pass locale, theme, and some CSS to frameStyle.

Recommended when all checkouts on your page share the same settings.

See: Paddle.Setup()

Pass items

Next, use the Paddle.checkout.open() method to open a checkout with your items.

Pass an array of objects, where each object contains 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.

If you already used the Paddle.Checkout.open() method in the previous step, add your items to that function.

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

Show and update on-page information

The inline checkout frame doesn't include a breakdown of items or totals. It's designed to handle capturing customer and payment information, letting you embed information about what your customer is buying on your page.

You should build your own logic to show items and totals in your frontend using Paddle.js events.

Pass an eventCallback to Paddle.Setup() to listen for events and update on-page elements. We recommend listening for:

Test your checkout

Open your checkout page in your browser and test. All things being well, the Paddle Checkout frame should appear in place of the checkout container element. Items and totals may be loaded, depending on your implementation.

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

Your eventCallback function and any other custom JavaScript that you wrote might be causing problems. Open your browser console to troubleshoot.

Extend your checkout

That's it! Now you've built a checkout, we recommend: