Integrate with a third-party address verification API

You might want to enhance the shopper experience by streamlining the process of populating and verifying the shipping address, thereby reducing the risk of user error. You can achieve this by implementing a third-party address lookup and autocomplete APIs, such as those provided by Google Places.

This tutorial describes how to override any field in a checkout address form and extend it to integrate with this service. The implementation supports backend-configurable validation and full form submission integration.

Upon successful completion of this tutorial, a form similar to the following will be displayed:

Autocomplete shipping address

Step-by-step

The following steps describe how to integrate the Google Address Validation API with the Commerce boilerplate template using the provided address autocomplete implementation.

Note

The commerce-checkout.js block is the only fully functional implementation that’s up-to-date with the latest checkout drop-in component. Use these steps as a reference when creating your own checkout experience.

Prerequisites

For this tutorial, you must have a valid Google API key. Use API keys describes the process to obtain and set up this key.

Note

The address autocomplete implementation includes a placeholder for the Google API key. You must replace ADD-YOUR-GOOGLE-API-KEY-HERE with your actual API key before using the implementation.

Download and configure the address autocomplete implementation

1. Download the implementation:

   Copy the address-autocomplete.js file from /public/samples/address-autocomplete.js in this documentation repository to your project directory.

2. Replace the API key placeholder:

   Open the address-autocomplete.js file and replace ADD-YOUR-GOOGLE-API-KEY-HERE with your actual Google API key:

   const CONFIG = {
       googleApiKey: 'YOUR_ACTUAL_GOOGLE_API_KEY',
       // ... rest of configuration
   };

Import and initialize the autocomplete service

In your commerce-checkout.js file, make the following changes to enable address autocomplete:

1. Import the autocomplete service:

   import { initializeAutocompleteWhenReady } from './address-autocomplete.js';

2. Initialize the autocomplete in the initializeCheckout function:

   const initializeCheckout = async () => {
     // ... existing checkout initialization code ...
   
     // Initialize address autocomplete for shipping form
     const shippingContainer = document.querySelector('[data-commerce-checkout-shipping]');
     if (shippingContainer) {
       initializeAutocompleteWhenReady(shippingContainer, 'input[name="street"]');
     }
   
     // ... rest of initialization code ...
   };

The initializeAutocompleteWhenReady function automatically:

• Waits for the address form to be rendered
• Attaches autocomplete functionality to the street input field
• Handles form field population when an address is selected
• Manages Google Maps API loading and initialization

Example

The complete address autocomplete implementation is available in /public/samples/address-autocomplete.js. This implementation includes:

• AddressAutocompleteService class: Handles Google Places API integration
• initializeAutocompleteWhenReady function: Utility function for easy integration
• Automatic form field population: Populates street, city, country, and postal code fields
• Keyboard navigation: Arrow keys, Enter, and Escape support
• Error handling: Graceful fallback when Google Maps API is unavailable

For additional customization options and advanced usage, see the implementation comments in the sample file.