Pass or update checkout items
Pass price IDs to Paddle.js to tell Paddle what a checkout is for. Use HTML data attributes or JavaScript properties.
As well as passing settings, you must pass an array of prices to a checkout before opening. This tells Paddle what the customer should be billed for.
How it works
When opening a checkout, pass a list of prices to it to tell Paddle what the checkout is for. You can pass properties to Paddle.Checkout.open()
or use HTML data attributes.
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.
Overlay checkout includes options for customers to change item quantities and remove items.
If you're using inline checkout, you can use the Paddle.Checkout.updateCheckout()
method to build your own logic to let customers add, remove, and update items.
Checkouts must have at least one item. You can't open a checkout without any items.
Before you begin
You'll need to include Paddle.js on your page and pass a client-side token.
To pass items to a checkout, you'll need to first create products and prices.
Get a step-by-step overview of how to build a complete checkout — including passing checkout settings. See: Build an overlay checkout or build an inline checkout
Pass items to a checkout
Pass a list of items
when opening a checkout to tell Paddle what this checkout is for. items
should contain an object for each item, with the price_id
for a price entity and a quantity
.
Pass items
to the Paddle.Checkout.open()
method or use the data-items
HTML data attribute on your checkout trigger element to do this.
This example passes three prices using Paddle.Checkout.open()
. The opened checkout is for these items.
123456789101112131415161Paddle.Checkout.open({
2 items: [
3 {
4 priceId: 'pri_01gsz8x8sawmvhz1pv30nge1ke',
5 quantity: 10
6 },
7 {
8 priceId: 'pri_01gsz95g2zrkagg294kpstx54r',
9 quantity: 1
10 },
11 {
12 priceId: 'pri_01gsz98e27ak2tyhexptwc58yk',
13 quantity: 1
14 }
15 ]
16});
Update items on a checkout
Overlay checkout
With overlay checkout, customers may change quantities and remove items — except where there's only one item left on a checkout. They can't add new items.
Inline checkout
The inline checkout frame captures customer and payment information. You can build your own logic to show the items list and interact with it. To update items:
Pass an
eventCallback
toPaddle.Initialize()
that listens for thecheckout.loaded
to display the on-page items list initially. Items are returned indata.items
against the event.Build logic to add or remove items and change quantities using the
Paddle.checkout.updateCheckout()
method. You may like to update discount at this point, too.Listen for
checkout.updated
in youreventCallback
to update the on-page items list.
For a complete example of an inline checkout that includes logic to dynamically update checkout items, see: Build an inline checkout
Prevent changes to items on a checkout
Overlay checkout
With overlay checkout, there's no built-in option to stop customers from removing or changing quantities of items on a checkout. However, you can:
Set quantity limits against a price.
You can set minimum and maximum quantities when creating a price to prevent customers from adding more or less of a price than they should. For example, a "Premium Support" addon might have a maximum quantity of
1
. Customers aren't able to change the quantity of this item on the checkout.Pass a billed transaction to Paddle.js.
Create a billed transaction using the Paddle API, then pass it to Paddle.js. Billed transactions cannot be changed, so customers aren't able to change the quantity of this item on the checkout.
Mark a transaction as
billed
onceready
.Paddle creates a related transaction for checkouts to handle calculations. You can use an
eventCallback
to listen for checkout events, then send a request to the Paddle API to mark a transaction as billed once it has the status ofready
. The quantity stepper is presented, but the checkout shows an error if customers try to change the quantity.
Inline checkout
When using inline checkout, the checkout frame doesn't include a breakdown of items or totals. It's handles capturing customer and payment information, letting you show information about what a customer is buying on your page.
When designing your inline checkout, we recommend building logic in your frontend if you need to prevent customers from removing or changing quantities