Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
About Stripe payments
Upgrade your integration
Payments analytics
Online payments
OverviewFind your use caseManaged Payments
Use Payment Links
Build a checkout page
Build an advanced integration
    Overview
    Quickstart
    Design an advanced integration
    Customize look and feel
    Manage payment methods
    Collect additional information
      Collect physical addresses and phone numbers
      Customize billing details collection
      Listen for address input
    Collect taxes on your payments
    Save the payment method used for a payment
    Save a payment method without making a payment
    Send receipts and paid invoices
Build an in-app integration
Payment methods
Add payment methods
Manage payment methods
Faster checkout with Link
Payment interfaces
Payment Links
Checkout
Web Elements
In-app Elements
Payment scenarios
Custom payment flows
Flexible acquiring
Orchestration
In-person payments
Terminal
Other Stripe products
Financial Connections
Crypto
Climate
HomePaymentsBuild an advanced integrationCollect additional information

Listen for address input

Collect addresses to use in custom ways using an event listener.

Copy page
Theme
Size
Customer Location

The Address Element enables you to collect local and international shipping or billing addresses from your customers.

Set up Stripe
Server-side

First, create a Stripe account or sign in.

Use our official libraries to access the Stripe API from your application:

Command Line
Ruby
# Available as a gem sudo gem install stripe
Gemfile
Ruby
# If you use bundler, you can add this line to your Gemfile gem 'stripe'

Collect address details
Client-side

You’re ready to collect address details on the client with the Address Element.

Set up Stripe.js

The Address Element is automatically available as a feature of Stripe.js. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.

checkout.html
<head> <title>Checkout</title> <script src="https://js.stripe.com/v3/"></script> </head>

Create a Stripe instance

Create an instance of Stripe on your checkout page:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Add the Address Element to your page

The Address Element needs a place on your page. Create an empty DOM node (container) with a unique ID in your form.

checkout.html
<form id="address-form"> <h3>Address</h3> <div id="address-element"> <!-- Elements will create form elements here --> </div> </form>

After this form loads, create an instance of the Address Element, specify the address mode and mount it to the container DOM node.

If you already have an Elements instance created, you can use the same instance to create the Address Element. Otherwise, create a new Elements instance first.

checkout.js
const options = { // Fully customizable with appearance API. appearance: { /* ... */ } }; // Only need to create this if no elements group exist yet. // Create a new Elements instance if needed, passing the // optional appearance object. const elements = stripe.elements(options); // Create and mount the Address Element in shipping mode const addressElement = elements.create("address", { mode: "shipping", }); addressElement.mount("#address-element");

Retrieve address details
Client-side

You can retrieve the address details by listening to the change event. The change event fires whenever the user updates any field in the Element.

addressElement.on('change', (event) => { if (event.complete){ // Extract potentially complete address const address = event.value.address; } })

Alternatively, you can use getValue.

checkout.js
const handleNextStep = async () => { const addressElement = elements.getElement('address'); const {complete, value} = await addressElement.getValue(); if (complete) { // Allow user to proceed to the next step // Optionally, use value to store the address details } };

In a single-page checkout flow with the Payment Element, the Address Element automatically passes the shipping or billing information when you confirm the PaymentIntent or SetupIntent.

In a multi-page checkout flow, you can manually update the PaymentIntent or update the Customer object with the address details received from the change event or getValue method before moving to the next step.

Configure the Address Element
Client-side

You can configure the Address Element to suit your needs.

Autocomplete

The Address Element has a built in address autocomplete feature that uses the Google Maps API Places Library. By default, the autocomplete is enabled with a Stripe provided Google Maps API key if any of the following conditions are met:

  • In a single page checkout flow where the Payment Element is mounted in the same elements group as the Address Element.
  • In a checkout flow that uses the Address Element in an active Link session.

To enable autocomplete in the Address Element for all other scenarios, you can use the autocomplete option with mode set to google_maps_api. Set the apiKey to be your own Google Maps API key that’s configured to allow the Places API usage. Your Google Maps API key is only used when the Stripe provided Google Maps API key isn’t available.

Note

If you’ve deployed a CSP and want to enable autocomplete with your own Google Maps API key, include https://maps.googleapis.com as a connect-src and script-src directive. Refer to the Google Maps API official guide for the most updated CSP requirement.

const addressElement = elements.create("address", { mode: "shipping", autocomplete: { mode: "google_maps_api", apiKey: "{YOUR_GOOGLE_MAPS_API_KEY}", }, });

Prefill address form

The Address Element accepts a defaultValues which lets you prefill the address form when the page loads. An Address Element with all values prefilled looks similar to:

const addressElement = elements.create("address", { mode: "shipping", defaultValues: { name: 'Jane Doe', address: { line1: '354 Oyster Point Blvd', line2: '', city: 'South San Francisco', state: 'CA', postal_code: '94080', country: 'US', }, }, });

Other options

Refer to Stripe.js for the complete list of options in detail.

// Sample of a options object const addressElement = elements.create("address", { mode: 'shipping', allowedCountries: ['US'], blockPoBox: true, fields: { phone: 'always', }, validation: { phone: { required: 'never', }, }, });

Validate address details
Client-side

Stripe provides a few ways to validate for completeness of an address and trigger errors such as “This field is incomplete.” to display on any incomplete individual address fields.

If you’re using the Address Element with a Payment Intent or Setup Intent, use stripe.confirmPayment or stripe.confirmSetup respectively to complete the intent and then validation errors will appear in the Address Element if there are any.

For other use cases such as multi-page checkout flow, use getValue to trigger validation errors to display in the Address Element.

OptionalCustomize the appearance
Client-side

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc