Paddle.Checkout.open()
Opens a checkout with settings, items, and customer information.
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
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.Initialize() 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. To learn more, see HTML data attributes
Parameters
Set general checkout settings.
Whether the user can change their email once on the checkout.
Whether the user can remove an applied discount at checkout. Defaults to true.
Payment options presented to customers at checkout.
Display mode for the checkout.
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.
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.
Class name of the <div> element where the checkout should be rendered.
Language for the checkout.
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.
Whether the option to add a tax number is displayed at checkout. Defaults to true.
URL to redirect to on checkout completion. Must start with http:// or https://.
Theme for the checkout.
Checkout experience presented to customers. Defaults to multi-page.
List of items for this checkout. You must pass at least one item. Use the updateItems() or updateCheckout() 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.
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.
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.
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.
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.
Examples
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.
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});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.
1234567891011121314151617181var 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 variant: "one-page"
16 },
17 items: itemsList,
18});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().
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: "jo@example.com",
16 address: {
17 countryCode: "US",
18 postalCode: "10021",
19 region: "New York",
20 city: "New York",
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.
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: {
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().
1231Paddle.Checkout.open({
2 transactionId: "txn_01gp3z8cfkqgdq07hcr3ja0q95"
3});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.
12345678910111213141516171var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 }
6];
7
8Paddle.Checkout.open({
9 customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
10 settings: {
11 displayMode: "inline",
12 frameTarget: "checkout-container",
13 frameInitialHeight: "450",
14 frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
15 items: itemsList
16 }
17});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 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.
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.
1234567891011121314151617181var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 }
6];
7
8Paddle.Checkout.open({
9 customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
10 savedPaymentMethodId: "paymtd_01hs8zx6x377xfsfrt2bqsevbw",
11 settings: {
12 displayMode: "inline",
13 frameTarget: "checkout-container",
14 frameInitialHeight: "450",
15 frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
16 items: itemsList
17 }
18});To learn more, see Present saved payment methods at checkout
Events
checkout.loaded | Emitted when the checkout opens. |
checkout.customer.created | Emitted when the checkout opens with customer properties prefilled. |