Collect physical addresses

Learn how to collect billing and shipping addresses.

Collect a billing address

By default, a Checkout Session collects the minimal billing details required for payment through the Payment Element.

Using the Billing Address Element

You can collect complete billing addresses using the Billing Address Element.

First, pass billing_address_collection=required when you create the Checkout Session.

Create a container DOM element to mount the Billing Address Element. Then create an instance of the Billing Address Element using checkout.createBillingAddressElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="billing-address"></div>

checkout.js
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.mount('#billing-address');

The Billing Address Element supports the following options:

Using a custom form

You can build your own form to collect billing addresses.

If your checkout page has a distinct address collection step before confirmation, call updateBillingAddress when your customer submits the address.
Otherwise, you can submit the address when your customer clicks the “pay” button by passing billingAddress to confirm.

Collect partial billing addresses

To collect partial billing addresses, such as only the country and postal code, pass billing_address_collection=auto.

When collecting partial billing addresses, you must collect addresses manually. By default, the Payment Element automatically collects the minimal billing details required for payment. To avoid double collection of billing details, pass fields.billingDetails=never when creating the Payment Element. If you only intend to collect a subset of billing details (such as the customer’s name), pass never for only the fields you intend to collect yourself.

Collect a shipping address

To collect a customer’s shipping address, pass the shipping_address_collection parameter when you create the Checkout Session.

When you collect a shipping address, you must also specify which countries to allow shipping to. Configure the allowed_countries property with an array of two-letter ISO country codes.

How to use the Shipping Address Element

You can collect complete shipping addresses with the Shipping Address Element.

Create a container DOM element to mount the Shipping Address Element. Then create an instance of the Shipping Address Element using checkout.createShippingAddressElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="shipping-address"></div>

checkout.js
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address');

The Shipping Address Element supports the following options:

How to use a custom form

You can build your own form to collect shipping addresses.

If your checkout page has a distinct address collection step before confirmation, call updateShippingAddress when your customer submits the address.
Otherwise, you can submit the address when your customer clicks the “pay” button by passing shippingAddress to confirm.