Paddle.Checkout.open()

Use Paddle.Checkout.open() to open a checkout.

Set the initial items list or transaction that this checkout is for
Set checkout settings, like the theme
Prefill checkout properties, like customer email and country
Send custom data to Paddle

To add items to a checkout, you can pass either:

An items array of objects, where each object contains a priceId and quantity property. priceId should be a Paddle ID of a price entity.
The Paddle ID of a transaction entity that you prepared earlier.

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.

To speed up checkout, or build workflows for logged-in customers, you can prefill customer, address, and business information. You can do this by passing customer, address, and business data, or by passing Paddle IDs for an existing customer, address, or business.

You can open a checkout for an upsell by passing an upsell object, containing the Paddle ID of the previously completed transaction that this upsell follows.

You can use the Paddle.Initialize() method to set default checkout settings. These settings apply to all checkouts opened on a page.

Parameters

settingsobject

Set general checkout settings.

allowLogoutboolean | null

Default: true

Whether the user can change their email once on the checkout.

allowDiscountRemovalboolean | null

Default: true

Whether the user can remove an applied discount at checkout. Defaults to true.

allowedPaymentMethodsarray | null

Payment options presented to customers at checkout.

Values

alipay
Alipay, popular in China.
apple_pay
Apple Pay on a supported Apple device.
bancontact
Bancontact, popular in Belgium.
blik
BLIK, a popular payment method in Poland.
card
Credit or debit card.

+ Show all values

google_pay
Google Pay on a supported Android device, Chromebook, or Google Chrome browser.
ideal
iDEAL, popular in the Netherlands.
kakao_pay
Kakao Pay, a popular payment method in Korea.
mb_way
MB WAY, a popular payment method in Portugal.
naver_pay
Naver Pay, a popular payment method in Korea.
payco
Payco, a popular payment method in Korea.
paypal
PayPal.
pix
Pix, popular in Brazil. Available in early access.
samsung_pay
Samsung Pay, a popular payment method in Korea.
saved_payment_methods
A customer's existing saved payment methods. Requires customerAuthToken to be passed to Paddle.Checkout.open().
south_korea_local_card
Korean local credit or debit card.
upi
Unified Payments Interface (UPI), popular in India. Available in early access.

displayModestring | null

Default: overlay

Display mode for the checkout.

Values

inline
Inline checkout mode. Checkout embedded as a frame in the page. Requires settings.frameTarget in Paddle.Initialize().
overlay
Overlay checkout mode. Checkout opens in an overlay.

frameInitialHeightstring | null

Example: 450

Height in pixels of the <div> on load. Do not include px. Recommended 450.

The inline checkout footer includes a message to let customers know that Paddle is the merchant of record for the transaction. For compliance, the inline checkout frame must be sized so that the footer message is visible.

frameStylestring | null

Example: min-width: 286px;background-color:transparent;

Styles to apply to the checkout <div>. min-width must be set to 286px or above with checkout padding off; 312px with checkout padding on. Use frameInitialHeight to set height.

frameTargetstring | null

Example: checkout-container

Class name of the <div> element where the checkout should be rendered.

localestring | null

Default: (browser default)

Language for the checkout. If omitted, the browser's default locale is used.

Values

ar
Arabic (العربية)
zh-Hans
Chinese (Simplified) (简化字)
zh-TW
Chinese (Traditional) (正體字)
da
Danish (Dansk)
nl
Dutch (Nederlands)

+ Show all values

en
English
fr
French (Français)
de
German (Deutsch)
it
Italian (Italiano)
ja
Japanese (日本語)
ko
Korean (한국어)
no
Norwegian (Norsk)
pl
Polish (Polski)
pt
Portuguese (Português)
pt-BR
Portuguese (Brazilian) (Português do Brasil)
tr
Turkish (Türkçe)
ru
Russian (Русский)
es
Spanish (Español)
sv
Swedish (Svenska)

showAddDiscountsboolean | null

Default: true

Whether the option to add a discount is displayed at checkout. Requires the "display discount field on the checkout" option enabled in Paddle > Checkout > Checkout settings. Defaults to true.

showAddTaxIdboolean | null

Default: true

Whether the option to add a tax number is displayed at checkout. Defaults to true.

successUrlstring | null

URL to redirect to on checkout completion. Must start with http:// or https://.

themestring | null

Default: light

Theme for the checkout. If omitted, defaults to light.

Values

light
Light-themed checkout.
dark
Dark-themed checkout.

variantstring | null

Default: multi-page

Checkout experience presented to customers. Defaults to multi-page.

Values

one-page
One-page checkout experience. Customer information and payment details collected on the same page.
multi-page
Multi-page checkout experience. Customer information and payment details collected on separate pages.

itemsarray

List of items for this checkout. You must pass at least one item. Use the updateItems() or updateCheckout() method to update the items list.

priceIdstring

Example: pri_01gm81eqze2vmmvhpjg13bfeqg

Paddle ID of the price for this item.

quantityinteger | null

Example: 1

Quantity for this line item.

transactionIdstring | null

Example: txn_01gp3z8cfkqgdq07hcr3ja0q95

Paddle ID of an existing transaction to use for this checkout. Use this instead of an items array to create a checkout for a transaction you previously created.

customerAuthTokenstring

Example: pca_01hstrngzv6v4ard25jgvywwqq_01hsgrwf0ev6gxm74bp0gebxas_o7scuiadqtvbtspkmbwfnyrvyrq3zig6

Authentication token for this customer, generated using the generate an authentication token for a customer operation in the Paddle API. Use to authenticate a customer so they can work with saved payment methods at checkout.

customerobject

Information about the customer for this checkout. Pass either an existing id, or the other fields.

idstring

Example: ctm_01gm82kny0ad1tk358gxmsq87m

Paddle ID of the customer for this checkout. Use if you know the customer, like if they're authenticated and making a change to their subscription. You can't use if you're passing email.

emailstring | null

Email for this customer. You can't use if you're passing id.

addressobject

Information about the customer address for this checkout. Pass either an existing id, or the other fields.

idstring | null

Example: add_01gm82v81g69n9hdb0v9sw6j40

Paddle ID for the customer address for this checkout. You can't use if you're passing any of the other address fields.

countryCodestring

Example: US

Two-letter ISO 3166 country code for this customer. You can't use if you're passing id.

postalCodestring

Example: 10021

ZIP or postal code of this address. Paddle Checkout only asks for this in countries with postal codes. You can't use if you're passing id.

regionstring

Example: California

State, county, or region of this address. Required if business is passed. You can't use if you're passing id.

citystring

Example: Newport Beach

City of this address. Required if business is passed. You can't use if you're passing id.

firstLinestring

Example: Balboa Center

First line of this address. Required if business is passed. You can't use if you're passing id.

businessobject

Information about the customer business for this checkout. Pass either an existing id, or the other fields.

idstring

Example: biz_01gnymqsj1etmestb4yhemdavm

Paddle ID for the customer business for this checkout. You can't use if you're passing name or taxIdentifier. Requires address.

namestring

Example: Paddle.com Inc

Name of the customer business. You can't use if you're passing id.

taxIdentifierstring

Example: GB08172165

Tax or VAT Number of the customer business. You can't use if you're passing id. Requires address.

discountCodestring | null

Example: BF20OFF

Discount code to apply to this checkout. Use to prepopulate a discount. Pass either discountCode or discountId.

discountIdstring | null

Example: dsc_01gtf15svsqzgp9325ss4ebmwt

Paddle ID of a discount to apply to this checkout. Use to prepopulate a discount. Pass either discountCode or discountId.

upsellobject | null

Opens a checkout as an upsell to display a streamlined checkout experience. Only works with inline, one-page checkouts.

transactionIdstringrequired

Example: txn_01gp3z8cfkqgdq07hcr3ja0q95

Unique Paddle ID for the previously completed transaction that this upsell follows, prefixed with txn_.

settingsobject | null

Configuration settings for the upsell checkout.

showSkipButtonboolean | null

Whether the "No thanks" skip button is shown at checkout. Defaults to true.

customDataobject | null

Example: { "crm_user_id": "123" }

Your own structured key-value data to include with this checkout. Passed data is held against the related transaction. If a transaction is for recurring items, custom data is copied to the related subscription when created. Must be valid JSON and contain at least one key.

savedPaymentMethodIdstring | null

Paddle ID for a saved payment method for this customer. If passed, only this saved payment method is presented at checkout. Use the list payment methods for a customer operation to get saved payment method IDs for a customer. Requires customerAuthToken.

Example

You can pass checkout settings using Paddle.Initialize(), or set them for each checkout in Paddle.Checkout.open().

This example includes the settings object as part of the checkout open method. Checkout is opened with these settings.

JavaScript

var itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

Paddle.Checkout.open({
  settings: {
    displayMode: "overlay",
    theme: "light",
    locale: "en",
  },
  items: itemsList,
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

const itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

paddle?.Checkout.open({
  settings: {
    displayMode: "overlay",
    theme: "light",
    locale: "en",
  },
  items: itemsList,
});

To learn more, see Pass checkout settings

You can pass checkout settings using Paddle.Initialize(), or set them for each checkout in Paddle.Checkout.open().

This example includes the settings object as part of the checkout open method, passing the required settings to open a one-page overlay checkout.

JavaScript

var itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

Paddle.Checkout.open({
  settings: {
    displayMode: "overlay",
    variant: "one-page",
  },
  items: itemsList,
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

const itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

paddle?.Checkout.open({
  settings: {
    displayMode: "overlay",
    variant: "one-page",
  },
  items: itemsList,
});

You can prefill checkout properties to speed up checkout.

This example includes customer, address, and business objects. Checkout is opened with this information prefilled, so customers land on the payment screen.

There's no settings object, so checkout settings must be included in Paddle.Initialize().

JavaScript

var itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

Paddle.Checkout.open({
  items: itemsList,
  customer: {
    email: "jo@example.com",
    address: {
      countryCode: "US",
      postalCode: "10021",
      region: "New York",
      city: "New York",
      firstLine: "4050 Jefferson Plaza, 41st Floor",
    },
    business: {
      name: "ChatApp Inc.",
      taxIdentifier: "555952383",
    },
  },
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

const itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

paddle?.Checkout.open({
  items: itemsList,
  customer: {
    email: "jo@example.com",
    address: {
      countryCode: "US",
      postalCode: "10021",
      region: "New York",
      city: "New York",
      firstLine: "4050 Jefferson Plaza, 41st Floor",
    },
    business: {
      name: "ChatApp Inc.",
      taxIdentifier: "555952383",
    },
  },
});

To learn more, see Prefill checkout properties

You can pass Paddle IDs for customers, addresses, and businesses to build upgrade workflows for logged-in customers.

This example includes a customer ID, address ID, and business ID. Checkout is opened with this information prefilled, so customers land on the payment screen.

allowLogout is false in the settings object, hiding the option to change the customer on the opened checkout.

JavaScript

var itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

Paddle.Checkout.open({
  settings: {
    displayMode: "overlay",
    theme: "light",
    locale: "en",
    allowLogout: false,
  },
  items: itemsList,
  customer: {
    id: "ctm_01gm82kny0ad1tk358gxmsq87m",
    address: {
      id: "add_01gm82v81g69n9hdb0v9sw6j40",
    },
    business: {
      id: "biz_01gnymqsj1etmestb4yhemdavm",
    },
  },
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

const itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
  {
    priceId: "pri_01gm82kny0ad1tk358gxmsq87m",
    quantity: 1,
  },
];

paddle?.Checkout.open({
  settings: {
    displayMode: "overlay",
    theme: "light",
    locale: "en",
    allowLogout: false,
  },
  items: itemsList,
  customer: {
    id: "ctm_01gm82kny0ad1tk358gxmsq87m",
    address: {
      id: "add_01gm82v81g69n9hdb0v9sw6j40",
    },
    business: {
      id: "biz_01gnymqsj1etmestb4yhemdavm",
    },
  },
});

To learn more, see Prefill checkout properties

You can create a transaction using the API or the Paddle dashboard, then pass it to a checkout to collect for it.

This example passes transactionID to open a checkout for that transaction.

There's no settings object, so checkout settings must be included in Paddle.Initialize().

JavaScript

Paddle.Checkout.open({
  transactionId: "txn_01gp3z8cfkqgdq07hcr3ja0q95",
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

paddle?.Checkout.open({
  transactionId: "txn_01gp3z8cfkqgdq07hcr3ja0q95",
});

To learn more, see Pass a transaction to a checkout

Customers can save payment methods when buying items using Paddle Checkout. You can then present customers with their saved payment methods when making purchases in the future.

You must pass customerAuthToken when opening a checkout to authenticate a customer and present them with their saved payment methods. You can generate an authentication token for a customer using the API.

This example passes customerAuthToken to Paddle.Checkout.open(), so customers are presented with their saved payment methods.

JavaScript

var itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
];

Paddle.Checkout.open({
  items: itemsList,
  customerAuthToken:
    "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: "450",
    frameStyle:
      "width: 100%; min-width: 312px; background-color: transparent; border: none;",
  },
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

const itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
];

paddle?.Checkout.open({
  items: itemsList,
  customerAuthToken:
    "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: 450,
    frameStyle:
      "width: 100%; min-width: 312px; background-color: transparent; border: none;",
  },
});

To learn more, see Present saved payment methods at checkout

Customers can save payment methods when buying items using Paddle Checkout. You can then present customers with their saved payment methods when making purchases in the future.

You can open a checkout for a specific a payment method that a customer has saved by using savedPaymentMethodId, passing the Paddle ID for a saved payment method. You can list payment methods for a customer using the API.

This example passes customerAuthToken and savedPaymentMethodId to Paddle.Checkout.open(), so customers are presented with the passed saved payment method.

JavaScript

var itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
];

Paddle.Checkout.open({
  customerAuthToken:
    "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  savedPaymentMethodId: "paymtd_01hs8zx6x377xfsfrt2bqsevbw",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: "450",
    frameStyle:
      "width: 100%; min-width: 312px; background-color: transparent; border: none;",
    items: itemsList,
  },
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

const itemsList = [
  {
    priceId: "pri_01gm81eqze2vmmvhpjg13bfeqg",
    quantity: 1,
  },
];

paddle?.Checkout.open({
  items: itemsList,
  customerAuthToken:
    "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  savedPaymentMethodId: "paymtd_01hs8zx6x377xfsfrt2bqsevbw",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: 450,
    frameStyle:
      "width: 100%; min-width: 312px; background-color: transparent; border: none;",
  },
});

To learn more, see Present saved payment methods at checkout

Upsell checkout is in early access

Access to Upsell checkout is limited to users who are part of our early access program. If you're interested in joining the program, review this guide and email us at sellers@paddle.com to apply. We'll reach out when space is available if you meet the program requirements.

You can present customers with a streamlined purchase flow for upsells at checkout to encourage them to upgrade or purchase additional items if they've previously completed a transaction.

This example passes the previously completed transaction ID as upsell.transactionId, and passes upsell.settings.showSkipButton: false to hide the "No thanks" skip button at checkout.

JavaScript

var upsellItems = [
  {
    priceId: "pri_01h1vjfevh5etwq3rb176h9d9w",
    quantity: 1,
  },
];

// previousTransactionId was captured from the initial checkout.completed event
Paddle.Checkout.open({
  items: upsellItems,
  customerAuthToken:
    "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: "450",
    frameStyle:
      "width: 100%; min-width: 312px; background-color: transparent; border: none;",
  },
  upsell: {
    transactionId: previousTransactionId,
    settings: {
      showSkipButton: false,
    },
  },
});

TypeScript

import { initializePaddle } from "@paddle/paddle-js";

const paddle = await initializePaddle({
  token: "live_7d279f61a3499fed520f7cd8c08",
});

const upsellItems = [
  {
    priceId: "pri_01h1vjfevh5etwq3rb176h9d9w",
    quantity: 1,
  },
];

// previousTransactionId was captured from the initial checkout.completed event
paddle?.Checkout.open({
  items: upsellItems,
  customerAuthToken:
    "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: 450,
    frameStyle:
      "width: 100%; min-width: 312px; background-color: transparent; border: none;",
  },
  upsell: {
    transactionId: previousTransactionId,
    settings: {
      showSkipButton: false,
    },
  },
});

To learn more, see Open a checkout for an upsell

`checkout.loaded`	Emitted when a checkout is created and loaded on the page.
`checkout.customer.created`	Emitted when a customer is created as part of checkout.

Paddle.Checkout.open()

Parameters

Example

Upsell checkout is in early access

Events

Was this page helpful?