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

# Prefill checkout properties

Prefill checkout fields to save customers time and increase checkout conversion

---

You can prefill properties on a checkout for a smoother checkout experience for customers. You might do this when:

- You capture some information about a prospect on the page before they interact with your checkout.
- You've built an integration with a CRM solution that passes email or other information as parameters on signup links.
- You're working with a logged-in customer, presenting them with upgrade options.

## How it works

[Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md) is optimized for conversion, asking customers for:

- Email address
- Country
- ZIP/postal code, or region ([only in some markets](https://developer.paddle.com/concepts/sell/supported-countries-locales.md))
- Payment details

Customers can also add a discount and information about their business, like a VAT or tax number.

You can pass data to a checkout to prefill properties, reducing purchase friction for customers and increasing conversion. You can prefill all customer details. You can't prefill payment details, but you can [present saved payment methods](https://developer.paddle.com/build/checkout/saved-payment-methods.md) for returning customers.

Prefilling works with both [overlay checkout](https://developer.paddle.com/build/checkout/build-overlay-checkout.md) and [inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md). You can use [HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes.md) or [JavaScript properties](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md).

## Before you begin

You'll need to [include Paddle.js on your page](https://developer.paddle.com/paddlejs/include-paddlejs.md) and pass a [client-side token](https://developer.paddle.com/paddlejs/client-side-tokens.md).

To open a checkout, you'll need to [create products and prices](https://developer.paddle.com/build/products/create-products-prices.md) and [pass them to a checkout](https://developer.paddle.com/build/checkout/pass-update-checkout-items.md).

{% callout type="note" %}
To get a step-by-step overview of how to build a complete checkout, including passing checkout settings and prefilling properties, see [Build an overlay checkout](https://developer.paddle.com/build/checkout/build-overlay-checkout.md) or [build an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md)
{% /callout %}

## Pass customer or business information

In this example, there's a signup button that includes an email address field. The page has a country selector.

You could use HTML attributes or JavaScript properties to prefill this information in checkout:

|  #  | Description       | HTML attribute                       | JavaScript property            |
|:---:|-------------------|--------------------------------------|--------------------------------|
| `1` | Country           | `data-customer-address-country-code` | `customer.address.countryCode` |
| `2` | Email address     | `data-customer-email`                | `customer.email`               |

{% tabs sync="js-html-implementation" %}
{% tab-item title="JavaScript properties" %}

Pass parameters to the `Paddle.Checkout.open()` method to prefill those values on a checkout.

<!-- Example showing passing customer details to Paddle.Checkout.open() -->
```javascript title="" highlightLines="[15,17]"
var itemsList = [
  {
    priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
    quantity: 1
  },
  {
    priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
    quantity: 1
  }
];

Paddle.Checkout.open({
  items: itemsList,
  customer: {
    email: "jo@example.com",
    address: {
      countryCode: "US",
      postalCode: "10021",
      region: "New York",
      city: "New York",
      firstLine: "4050 Jefferson Plaza, 41st Floor"
    },
    business: {
      name: "ChatApp Inc.",
      taxIdentifier: "555952383"
    }
  }
});
```

For a full list of fields that you can prefill, see [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md)

{% callout type="note" %}
You can update properties on an open checkout using the [`Paddle.Checkout.updateCheckout()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-updatecheckout.md) method.
{% /callout %}

{% /tab-item %}
{% tab-item title="HTML data attributes" %}

Add data attributes to your checkout launcher to prefill those values on a checkout.

```html title="Checkout launcher element" highlightLines="5-6"
<a 
  href='#' 
  class='paddle_button'
  data-theme='light'
  data-customer-address-country-code='US'
  data-customer-email='jo@example.com'
  data-items='[
    {
      "priceId": "pri_01gs59hve0hrz6nyybj56z04eq",
      "quantity": 1
    },
    {
      "priceId": "pri_01gs59p7rcxmzab2dm3gfqq00a",
      "quantity": 1
    }
  ]'
>
  Buy Now
</a>
```

For a full list of fields you can prefill, see [HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes.md)

{% /tab-item %}
{% /tabs %}

## Pass customer, address, and business IDs

Instead of passing customer email, address, and business information, you can pass an existing customer ID, address ID, or business ID.

You might do this if you're working with a logged-in customer who's looking to upgrade or purchase another subscription, or if you have a CRM integration that creates entities in Paddle for prospects.

{% callout type="info" %}
Customer ID, address ID, and business ID replace other customer, address, and business fields. For example, you should pass either customer ID or customer email — not both.
{% /callout %}

{% tabs sync="js-html-implementation" %}
{% tab-item title="JavaScript" %}

Pass parameters to the `Paddle.Checkout.open()` method to prefill those values on a checkout.

<!-- Example showing passing Paddle IDs to Paddle.Checkout.open() -->
```javascript title="" highlightLines="[20,21,22,23,24,25,26,27,28]"
var itemsList = [
  {
    priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
    quantity: 1
  },
  {
    priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
    quantity: 1
  }
];

Paddle.Checkout.open({
  settings: {
    displayMode: "overlay",
    theme: "light",
    locale: "en",
    allowLogout: false
  },
  items: itemsList,
  customer: {
    id: "ctm_01gm82kny0ad1tk358gxmsq87m",
    address: {
      id: "add_01gm82v81g69n9hdb0v9sw6j40"
    },
    business: {
      id: "biz_01gnymqsj1etmestb4yhemdavm"
    }
  }
});
```

For a full list of fields that you can prefill, see [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md)

{% callout type="note" %}
You can update properties on an open checkout using the [`Paddle.Checkout.updateCheckout()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-updatecheckout.md) method.
{% /callout %}

{% /tab-item %}
{% tab-item title="HTML data attributes" %}

Add data attributes to your checkout launcher to prefill those values on a checkout.

```html title="Checkout launcher element" highlightLines="5-7"
<a 
  href='#' 
  class='paddle_button'
  data-theme='light'
  data-customer-id='ctm_01gm82kny0ad1tk358gxmsq87m'
  data-customer-address-id='add_01gm82v81g69n9hdb0v9sw6j40'
  data-business-id='biz_01gnymqsj1etmestb4yhemdavm'
  data-items='[
    {
      "priceId": "pri_01gm81eqze2vmmvhpjg13bfeqg",
      "quantity": 1
    },
    {
      "priceId": "pri_01gm82kny0ad1tk358gxmsq87m",
      "quantity": 1
    }
  ]'
>
  Buy Now
</a>
```

For a full list of fields that you can prefill, see [HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes.md)

{% /tab-item %}
{% /tabs %}

## Apply a discount

You can pass the Paddle ID of a discount entity or its discount code to a checkout to automatically apply it — no need for customers to enter a code.

{% callout type="info" %}
`enabled_for_checkout` must be `true` against [the discount entity](https://developer.paddle.com/api-reference/discounts/overview.md) to apply it to a checkout.  
{% /callout %}

{% tabs sync="js-html-implementation" %}
{% tab-item title="JavaScript" %}

Pass parameters to the `Paddle.Checkout.open()` method to prefill those values on a checkout.

<!-- Example showing passing settings and a discount to Paddle.Checkout.open() -->
```javascript title="" highlightLines="[6]"
Paddle.Checkout.open({
  settings: {
    theme: "light",
    locale: "en"
  },
  discountId: "dsc_01gp0ynsntfpyw2spd2md1wqx1",
  items: [
    {
      priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
      quantity: 1
    },
    {
      priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
      quantity: 1
    },
    {
      priceId: 'pri_01gm82v81g69n9hdb0v9sw6j40',
      quantity: 1
    }
  ]
});
```

To learn more, see [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md)

{% callout type="note" %}
You can update properties on an open checkout using the [`Paddle.Checkout.updateCheckout()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-updatecheckout.md) method.
{% /callout %}

{% /tab-item %}
{% tab-item title="HTML data attributes" %}

Add data attributes to your checkout launcher to prefill those values on a checkout.

```html title="Checkout launcher element" highlightLines="20"
<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
      },
      {
          "priceId": "pri_01gm82v81g69n9hdb0v9sw6j40",
          "quantity": 1
      }
  ]'
  data-discount-id='dsc_01gp0ynsntfpyw2spd2md1wqx1'
>
 Buy now
</a>
```

To learn more, see [HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes.md)

{% /tab-item %}
{% /tabs %}

## Build a one-page checkout

### One-page checkout experience

Pass `variant` with the value `one-page` as [a checkout setting](https://developer.paddle.com/build/checkout/set-up-checkout-default-settings.md) to present customers with a one-page checkout experience. Paddle Checkout collects customer information and payment details on the same page.

<!-- Example showing opening a one-page overlay checkout -->
```javascript title="" highlightLines="[16]"
var itemsList = [
  {
    priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
    quantity: 1
  },
  {
    priceId: 'pri_01gm82kny0ad1tk358gxmsq87m',
    quantity: 1
  }
];

Paddle.Checkout.open({
  settings: {
    displayMode: "overlay",
    variant: "one-page"
  },
  items: itemsList,
});
```

### Multi-page checkout

If you prefer the multi-page checkout experience, Paddle skips the first page of checkout when all required fields are prefilled. This means customers land on a screen where all they need to do is enter their payment details.

To jump to the second page on the multi-page inline checkout, prefill either required properties or Paddle IDs:

{% accordion %}
{% accordion-item title="Required properties" %}

| Description                                                                          | HTML attribute                       | JavaScript property            |
|--------------------------------------------------------------------------------------|--------------------------------------|--------------------------------|
| Country                                                                              | `data-customer-address-country-code` | `customer.address.countryCode` |
| Email address                                                                        | `data-customer-email`                | `customer.email`               |
| ZIP/postal code ([only where required](https://developer.paddle.com/concepts/sell/supported-countries-locales.md))  | `data-customer-address-postal-code`  | `customer.address.postalCode`  |
| Region ([only for United Arab Emirates](https://developer.paddle.com/concepts/sell/supported-countries-locales.md)) | `data-customer-address-region`       | `customer.address.region`      |

{% /accordion-item %}
{% accordion-item title="Paddle IDs" %}

| Description                                                                                                   | HTML attribute             | JavaScript property   |
|---------------------------------------------------------------------------------------------------------------|----------------------------|-----------------------|
| Customer ID                                                                                                   | `data-customer-id`         | `customer.id`         |
| Address ID, with valid ZIP/postal code or region [where required](https://developer.paddle.com/concepts/sell/supported-countries-locales.md) | `data-customer-address-id` | `customer.address.id` |

{% /accordion-item %}
{% /accordion %}