Paddle Billing
Search

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 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 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. See: HTML data attributes

Parameters

settingsobject

Set general checkout settings.

allowLogoutboolean or null

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

allowDiscountRemovalboolean or null

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

allowedPaymentMethodsarray[string] or null

Payment options presented to customers at checkout.

displayModestring or null

Display mode for the checkout.

frameInitialHeightstring or null

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<css> or null

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 or null

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

localestring or null

Language for the checkout.

showAddDiscountsboolean or null

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

showAddTaxIdboolean or null

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

successUrlstring<uri> or null

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

themestring or null

Theme for the checkout.

variantstring or null

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

Only valid where displayMode is inline; ignored otherwise.

itemsarray[object]

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<Paddle ID>

Paddle ID of the price for this item.

quantityinteger or null

Quantity for this line item.

transactionIdstring<Paddle ID> or null

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.

customerobject

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

idstring<Paddle ID>

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

businessobject

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

discountCodestring or null

Discount code to apply to this checkout. Use to pre-populate a discount. Pass either discountCode or discountId.

discountIdstring<Paddle ID> or null

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

customDataobject or null

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.

Examples

Events

checkout.loadedEmitted when the checkout opens.
checkout.customer.createdEmitted when the checkout opens with customer properties prefilled.

Related pages