> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# HTML data attributes

Use HTML data attributes to pass parameters to a checkout, rather than using JavaScript properties.

---

You can use HTML data attributes to open a checkout with settings, items, and customer information. They're typically used with [overlay checkouts](https://developer.paddle.com/concepts/sell/overlay-checkout.md) in websites or apps where you don't have full control over the page layout.

Data attributes support all the same properties as the [`Paddle.Checkout.open()`](https://developer.paddle.com/paddle-js/methods/paddle-checkout-open.md) method, letting you:

- Set the initial items list or transaction that a checkout is for
- Set checkout settings, like the theme
- Prefill checkout properties, like customer email and country
- Send [custom data](https://developer.paddle.com/build/transactions/custom-data.md) to Paddle

Set data attributes on the element that you've turned into a Paddle Checkout button to open a checkout with the properties.

## Before you begin

You must [include and initialize Paddle.js](https://developer.paddle.com/paddle-js/include-paddlejs.md) to use HTML data attributes, but you don't need to use any other JavaScript if you're working with an overlay checkout.

## List of attributes

```yaml
title: HTML data attributes
type: object
properties:
  data-display-mode:
    type: string
    description: Display mode for the checkout.
    enum:
      - inline
      - overlay
    x-enum-descriptions:
      inline:
        description: >-
          Inline checkout mode. Checkout embedded as a frame in the page. Requires `frameTarget` in
          `Paddle.Initialize()`.
      overlay:
        description: Overlay checkout mode. Checkout opens in an overlay.
  data-theme:
    type: string
    description: Theme for the checkout.
    enum:
      - light
      - dark
    x-enum-descriptions:
      light:
        description: Light-themed checkout.
      dark:
        description: Dark-themed checkout.
  data-locale:
    type: string
    default: (browser default)
    description: Language for the checkout.
    enum:
      - ar
      - zh-Hans
      - zh-TW
      - da
      - nl
      - en
      - fr
      - de
      - it
      - ja
      - ko
      - "no"
      - pl
      - pt
      - tr
      - ru
      - es
      - sv
    x-enum-descriptions:
      ar:
        description: Arabic (العربية)
      zh-Hans:
        description: Chinese (Simplified) (简化字)
      zh-TW:
        description: Chinese (Traditional) (正體字)
      da:
        description: Danish (Dansk)
      nl:
        description: Dutch (Nederlands)
      en:
        description: English
      fr:
        description: French (Français)
      de:
        description: German (Deutsch)
      it:
        description: Italian (Italiano)
      ja:
        description: Japanese (日本語)
      ko:
        description: Korean (한국어)
      "no":
        description: Norwegian (Norsk)
      pl:
        description: Polish (Polski)
      pt:
        description: Portuguese (Português)
      tr:
        description: Turkish (Türkçe)
      ru:
        description: Russian (Русский)
      es:
        description: Spanish (Español)
      sv:
        description: Swedish (Svenska)
  data-success-url:
    type: string
    description: URL to redirect to on checkout completion.
  data-allow-logout:
    type: boolean
    default: true
    description: Whether the user can change their email once on the checkout.
  data-allow-discount-removal:
    type: boolean
    default: true
    description: Whether the user can remove an applied discount at checkout. Defaults to `true`.
  data-items:
    type: array
    description: List of items for this checkout. You must pass at least one item.
    items:
      type: object
      properties:
        priceId:
          type: string
          examples:
            - pri_01gm81eqze2vmmvhpjg13bfeqg
          description: Paddle ID of the price for this item.
        quantity:
          type: number
          examples:
            - 1
          description: Quantity for this line item.
  data-transaction-id:
    type: string
    examples:
      - txn_01gp3z8cfkqgdq07hcr3ja0q95
    description: >-
      Paddle ID of an existing transaction to use for this checkout. Use this instead of an `data-items` array to create
      a checkout for a transaction you previously created.
  data-customer-id:
    type: string
    examples:
      - ctm_01gm82kny0ad1tk358gxmsq87m
    description: >-
      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 `data-customer-email`.
  data-customer-email:
    type: string
    description: Email for this customer. You can't use if you're passing `data-customer-id`.
  data-customer-address-id:
    type: string
    examples:
      - add_01gm82v81g69n9hdb0v9sw6j40
    description: >-
      Paddle ID for the customer address for this checkout. You can't use if you're passing
      `data-customer-address-country-code` or `data-customer-address-postal-code`.
  data-customer-address-country-code:
    type: string
    examples:
      - US
    description: Two-letter ISO 3166 country code for this customer. You can't use if you're passing `data-customer-address-id`.
  data-customer-address-postal-code:
    type: string
    examples:
      - "92663"
    description: >-
      ZIP or postal code of this address. Required for countries with postal codes. You can't use if you're passing
      `data-customer-address-id`.
  data-customer-address-region:
    type: string
    examples:
      - California
    description: State, county, or region of this address. Required if `data-business-` properties are passed.
  data-customer-address-city:
    type: string
    examples:
      - Newport Beach
    description: City of this address. Required if `data-business-` properties are passed.
  data-customer-address-first-line:
    type: string
    examples:
      - Balboa Center
    description: First line of this address. Required if `data-business-` properties are passed.
  data-business-id:
    type: string
    examples:
      - biz_01gnymqsj1etmestb4yhemdavm
    description: >-
      Paddle ID for the customer business for this checkout. You can't use if you're passing `data-business-name` or
      `data-business-tax-id`.
  data-business-name:
    type: string
    examples:
      - Paddle.com Inc
    description: Name of the customer business. You can't use if you're passing `data-business-id`.
  data-business-tax-id:
    type: string
    examples:
      - GB08172165
    description: Tax or VAT Number of the customer business. You can't use if you're passing `data-business-id`.
  data-show-add-discounts:
    type: boolean
    default: true
    description: Whether the option to add a discount is displayed at checkout. Defaults to `true`.
  data-discount-code:
    type: string
    examples:
      - BF20OFF
    description: >-
      Discount code to apply to this checkout. Use to prepopulate a discount. Pass either `data-discount-code` or
      `data-discount-id`.
  data-discount-id:
    type: string
    examples:
      - dsc_01gp0ynsntfpyw2spd2md1wqx1
    description: >-
      Paddle ID of a discount to apply to this checkout. Use to prepopulate a discount. Pass either `data-discount-code`
      or `data-discount-id`.
  data-custom-data:
    type: object
    examples:
      - '{ "crm_user_id": "123" }'
    description: Custom key-value data to include with the checkout. Must be valid JSON and contain at least one key.
  data-variant:
    type: string
    default: multi-page
    description: Checkout experience presented to customers. Defaults to `multi-page`.
    enum:
      - one-page
      - multi-page
    x-enum-descriptions:
      one-page:
        description: One-page checkout experience. Customer information and payment details collected on the same page.
      multi-page:
        description: Multi-page checkout experience. Customer information and payment details collected on separate pages.
  data-upsell-transaction-id:
    type: string
    examples:
      - txn_01gp3z8cfkqgdq07hcr3ja0q95
    description: Paddle ID for the previously completed transaction that this upsell follows, prefixed with `txn_`.
  data-upsell-show-skip-button:
    type: boolean
    default: true
    description: Whether the "No thanks" skip button is displayed at checkout. Defaults to `true`.
```

## Examples

{% accordion %}
{% accordion-item title="Checkout with settings and items" %}

This example includes checkout settings and items.

```html {% highlightLines="2-15" %}
<a href='#' 
  class='paddle_button'
  data-display-mode='overlay'
  data-theme='light'
  data-locale='en'
  data-items='[
    {
      "priceId": "pri_01gm81eqze2vmmvhpjg13bfeqg",
      "quantity": 1
    },
    {
      "priceId": "pri_01gm82kny0ad1tk358gxmsq87m",
      "quantity": 1
    }
  ]'
>
  Buy now
</a>
```

{% /accordion-item %}

{% accordion-item title="Checkout with customer, address, and business information prefilled" %}

You can prefill checkout properties to speed up checkout.

This example includes `customer`, `address`, and `business` information. Checkout is opened with this information prefilled, so customers land on the payment screen.

```html {% highlightLines="16-23" %}
<a href='#' 
  class='paddle_button'
  data-display-mode='overlay'
  data-theme='light'
  data-locale='en'
  data-items='[
    {
      "priceId": "pri_01gm81eqze2vmmvhpjg13bfeqg",
      "quantity": 1
    },
    {
      "priceId": "pri_01gm82kny0ad1tk358gxmsq87m",
      "quantity": 1
    }
  ]'
  data-customer-email='weloveyourproduct@paddle.com'
  data-customer-address-country-code='US'
  data-customer-address-postal-code='92663'
  data-customer-address-region='California'
  data-customer-address-city='Newport Beach'
  data-customer-address-first-line='Balboa Center'
  data-business-name='Paddle.com, Inc'
  data-business-tax-id='GB802311782'
>
  Buy now
</a>
```

{% /accordion-item %}

{% accordion-item title="Checkout with customer, address, and business as Paddle IDs" %}

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.

`data-allow-logout` is `false`, hiding the option to change the customer on the opened checkout.

```html {% highlightLines="17-19" %}
<a href='#' 
  class='paddle_button'
  data-display-mode='overlay'
  data-theme='light'
  data-locale='en'
  data-allow-logout='false'
  data-items='[
    {
      "priceId": "pri_01gm81eqze2vmmvhpjg13bfeqg",
      "quantity": 1
    },
    {
      "priceId": "pri_01gm82kny0ad1tk358gxmsq87m",
      "quantity": 1
    }
  ]'
  data-customer-id='ctm_01gm82kny0ad1tk358gxmsq87m'
  data-customer-address-id='add_01gm82v81g69n9hdb0v9sw6j40'
  data-business-id='biz_01gnymqsj1etmestb4yhemdavm'
>
  Buy now
</a>
```

{% /accordion-item %}

{% /accordion %}