Docs

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 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() 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 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 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

data-display-modestring
Display mode for the checkout.
Values
  • inline
    Inline checkout mode. Checkout embedded as a frame in the page. Requires frameTarget in Paddle.Initialize().
  • overlay
    Overlay checkout mode. Checkout opens in an overlay.
data-themestring
Theme for the checkout.
Values
  • light
    Light-themed checkout.
  • dark
    Dark-themed checkout.
data-localestring
Default: (browser default)
Language for the checkout.
Values
  • ar
    Arabic (العربية)
  • zh-Hans
    Chinese (Simplified) (简化字)
  • zh-TW
    Chinese (Traditional) (正體字)
  • da
    Danish (Dansk)
  • nl
    Dutch (Nederlands)
+ Show all values
  • en
    English
  • fr
    French (Français)
  • de
    German (Deutsch)
  • it
    Italian (Italiano)
  • ja
    Japanese (日本語)
  • ko
    Korean (한국어)
  • no
    Norwegian (Norsk)
  • pl
    Polish (Polski)
  • pt
    Portuguese (Português)
  • tr
    Turkish (Türkçe)
  • ru
    Russian (Русский)
  • es
    Spanish (Español)
  • sv
    Swedish (Svenska)
data-success-urlstring
URL to redirect to on checkout completion.
data-allow-logoutboolean
Default: true
Whether the user can change their email once on the checkout.
data-allow-discount-removalboolean
Default: true
Whether the user can remove an applied discount at checkout. Defaults to true.
data-itemsarray
List of items for this checkout. You must pass at least one item.
priceIdstring
Example: pri_01gm81eqze2vmmvhpjg13bfeqg
Paddle ID of the price for this item.
quantitynumber
Example: 1
Quantity for this line item.
data-transaction-idstring
Example: txn_01gp3z8cfkqgdq07hcr3ja0q95
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-idstring
Example: ctm_01gm82kny0ad1tk358gxmsq87m
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-emailstring
Email for this customer. You can't use if you're passing data-customer-id.
data-customer-address-idstring
Example: add_01gm82v81g69n9hdb0v9sw6j40
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-codestring
Example: US
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-codestring
Example: 92663
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-regionstring
Example: California
State, county, or region of this address. Required if data-business- properties are passed.
data-customer-address-citystring
Example: Newport Beach
City of this address. Required if data-business- properties are passed.
data-customer-address-first-linestring
Example: Balboa Center
First line of this address. Required if data-business- properties are passed.
data-business-idstring
Example: biz_01gnymqsj1etmestb4yhemdavm
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-namestring
Example: Paddle.com Inc
Name of the customer business. You can't use if you're passing data-business-id.
data-business-tax-idstring
Example: GB08172165
Tax or VAT Number of the customer business. You can't use if you're passing data-business-id.
data-show-add-discountsboolean
Default: true
Whether the option to add a discount is displayed at checkout. Defaults to true.
data-discount-codestring
Example: BF20OFF
Discount code to apply to this checkout. Use to prepopulate a discount. Pass either data-discount-code or data-discount-id.
data-discount-idstring
Example: dsc_01gp0ynsntfpyw2spd2md1wqx1
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-dataobject
Example: { "crm_user_id": "123" }
Custom key-value data to include with the checkout. Must be valid JSON and contain at least one key.
data-variantstring
Default: multi-page
Checkout experience presented to customers. Defaults to multi-page.
Values
  • one-page
    One-page checkout experience. Customer information and payment details collected on the same page.
  • multi-page
    Multi-page checkout experience. Customer information and payment details collected on separate pages.
data-upsell-transaction-idstring
Example: txn_01gp3z8cfkqgdq07hcr3ja0q95
Paddle ID for the previously completed transaction that this upsell follows, prefixed with txn_.
data-upsell-show-skip-buttonboolean
Default: true
Whether the "No thanks" skip button is displayed at checkout. Defaults to true.

Examples

This example includes checkout settings and items.

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

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

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

Was this page helpful?