Pass or update checkout items

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.

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 and Retain API key.

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.

Use the data-items HTML data attribute on your checkout trigger element, or pass items to the Paddle.Checkout.open() method to do this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1<a 
2  href='#'
3  class='paddle_button'
4  data-display-mode='overlay'
5  data-theme='light'
6  data-locale='en'
7  data-items='[
8    {
9      "priceId": "pri_01gsz8x8sawmvhz1pv30nge1ke",
10      "quantity": 10
11    },
12    {
13      "priceId": "pri_01gsz95g2zrkagg294kpstx54r",
14      "quantity": 1
15    },
16    {
17      "priceId": "pri_01gsz98e27ak2tyhexptwc58yk",
18      "quantity": 1
19    }
20  ]'

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:

1. Pass an eventCallback to Paddle.Initialize() that listens for the checkout.loaded event to display the on-page items list initially. Items are returned in data.items against the event.

2. 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.

3. Listen for checkout.updated in your eventCallback to update the on-page items list.

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 increment the quantity of this item on the checkout.

• Mark a transaction as billed once ready.

  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 of ready. Customers aren't able to change items as billed transactions can't be changed.

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 your 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

Related pages