Paddle.Checkout.open()
Opens a checkout with settings, items, and customer information.
Use Paddle.Checkout.open() to open and interact with a checkout. This is one of the core methods in Paddle.js, letting you:
- 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
itemsarray of objects, where each object contains apriceIdandquantityproperty.priceIdshould 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 use the Paddle.Setup() method to set default checkout settings. These settings apply to all checkouts opened on a page.
Instead of using
Paddle.Checkout.open(), you can use HTML data attributes to open a checkout. This is ideal when working with a CMS that has limited customization options, or if you're not comfortable with JavaScript. See: HTML data attributes
Parameters
Set general checkout settings.
Display mode for the checkout.
Theme for the checkout.
Language for the checkout.
Whether the user can change their email once on the checkout.
Class name of the <div> element where the checkout should be rendered.
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.
Height in pixels of the <div> on load. Do not include px. Recommended 450.
URL to redirect to on checkout completion.
List of items for this checkout. You must pass at least one item. Use the updateItems() method to update the items list.
Paddle ID of the price for this item.
Quantity for this line item.
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.
Information about the customer for this checkout. Pass either an existing id, or the other fields.
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.
Email for this customer. You can't use if you're passing id.
Information about the customer address for this checkout. Pass either an existing id, or the other fields.
Information about the customer business for this checkout. Pass either an existing id, or the other fields.
Discount code to apply to this checkout. Use to pre-populate a discount. Pass either discountCode or discountId.
Paddle ID of a discount to apply to this checkout. Use to pre-populate a discount. Pass either discountCode or discountId.
Custom key-value data to include with the checkout. Must be valid JSON and contain at least one key.
Examples
You can set checkout settings using Paddle.Setup(), 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.
123456789101112131415161718191var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 },
6 {
7 priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
8 quantity: 1
9 }
10];
11
12Paddle.Checkout.open({
13 settings: {
14 displayMode: "overlay",
15 theme: "light",
16 locale: "en"
17 },
18 items: itemsList,
19});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.Setup().
12345678910111213141516171819201var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 },
6 {
7 priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
8 quantity: 1
9 }
10];
11
12Paddle.Checkout.open({
13 items: itemsList,
14 customer: {
15 email: "weloveyourproduct@paddle.com",
16 address: {
17 countryCode: "US",
18 postalCode: "92663",
19 region: "California",
20 city: "Newport Beach",
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.
12345678910111213141516171819201var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 },
6 {
7 priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
8 quantity: 1
9 }
10];
11
12Paddle.Checkout.open({
13 settings: {
14 displayMode: "overlay",
15 theme: "light",
16 locale: "en",
17 allowLogout: false
18 },
19 items: itemsList,
20 customer: {
You can set up a transaction using the API or 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.Setup().
1231Paddle.Checkout.open({
2 transactionId: "txn_01gp3z8cfkqgdq07hcr3ja0q95"
3});Notifications
checkout.loaded | Emitted when the checkout opens. |
checkout.customer.created | Emitted when the checkout opens with customer properties prefilled. |
