The Loqate Shopify Plus Integration Guide

The Loqate Shopify Plus Integration, downloadable via the Shopify App Store, allows you to quickly and easily add Loqate's address validation services to the checkout page of your Shopify Plus site. With some or all of these services enabled you can provide your customers with type-ahead lookup functionality for address fields (reducing both input times and the likelihood of errors), verification for manually-entered addresses, and email address validation.

We've created this integration to take advantage of Shopify's new Checkout Extensibility functionality, which means you can leverage Shopify's latest technology as part of the Loqate app.

Installing and setting up this Shopify Plus app is a straightforward process, and in this guide we will take you through the handful of quick steps required to get up and running. You don't need any in-depth technical knowledge in order to install this app, just familiarity with Shopify Plus.

Available services: Address Capture, Address Verify and Email Validation

The Loqate Shopify Plus Integration includes three Loqate services:

• Address Capture, which provides a type-ahead solution for address input
• Address Verify, which ensures the accuracy of manually-entered addresses
• Email Validation, which ensures the accuracy of customer email addresses

Read on to find out more about what each service does, and how they complement each other. 

Address Capture

This is active by default once you've installed and configured the app, adding type-ahead address lookup functionality to the Address field on your checkout form and allowing customers to start typing in their address and then select the relevant one from a list of suggested addresses.

Address Capture is available in both the Delivery address and Billing address sections.

Address Verify

This is an optional feature available in the Delivery address section which, if enabled, adds an extra layer of verification. If a customer selects their address using the Address Capture type-ahead solution, there's no need to verify that address so Address Verify isn't used. If, however, a customer chooses to manually enter their address instead, Address Verify will check that address against our reference data using a process of correction, standardisation, formatting, enhancement and verification. If appropriate, it can then either automatically make small corrections, or offer an alternative which the customer can either agree to use, or dismiss in favour of their original entry.

The accuracy of a manually inputted address is presented as an Address Verification Code (or AVC), which you can read more about here. Customers don't see that score, but it's used to determine the thresholds for when to autocorrect an address, and when Address Verify will offer suggestions for alternative addresses. You can choose the threshold for autocorrections, while the suggestion thresholds are automated within Address Verify. For example:

• 'Good addresses' (i.e. which are verified or partially verified to levels 4 or 5, and return a Matchscore of 95% or above): we recommend autocorrecting small changes (i.e. a character or two) for these addresses
• 'Questionable addresses' (i.e. which are verified or partially verified to levels 4 or 5, and return a Matchscore of above 80%): you could autocorrect an address within this range, or instead choose to prompt the customer with an alternative address
• 'Poor quality addresses' (i.e. which are verified to levels 3 or below, or return a Matchscore of below 80%): Address Verify will either prompt the customer to check the address they inputted and confirm that it's correct, or flag that the address can't be found

You can choose how to use these thresholds based on your own business requirements. When a customer's manually-entered address falls below your chosen threshold, either it will be autocorrected or they will be prompted with a suggestion of a new address, and asked to confirm whether they would like to use the suggested address or stick with their original choice.

Address Verify is only available in the Delivery address section, and only available for non-logged-in users.

Email Validation

This is an optional feature which, if enabled, allows you to validate customer email addresses as they're being entered. If a customer enters an invalid email address*, they will be notified that the email address can't be validated and won't be able to proceed through the checkout form until they enter a valid email address.

Otherwise, customers who enter valid email addresses will not have their experience interrupted or visually altered in any way.

*See the 'Response fields' section of the Email Validation API documentation for details of why an email address might be invalid.

Prerequisites

Before you start installing and setting up the Loqate Shopify Plus Integration, you will need the following:

• A live Shopify Plus account
• A live Loqate account
• A new Loqate API key (see the API keys section below for more information on this)

Loqate accounts

You can use the Loqate Shopify Plus app with both the Loqate Saas platform (available to North American customers) and Classic platform. If you're in the US and you're not sure which platform you're using, see our guide to the Loqate Saas Platform.

It's important to note, however, that Address Verify functionality is only available via the Classic platform. You can use both Address Capture and Address Verify with a single Classic platform API key. 

API keys

You'll need a new Loqate API key, dedicated to this service (our Creating API Keys page has lots of information about how to set one up, and what to consider when you're doing that). For the Loqate Saas platform you can use any key; for the Classic platform we recommend you create a generic API key, but any key will work.

For information about how to ensure your Loqate integration is as secure as possible, see our API Security page.

Installation

There are a few quick steps to get the Loqate Shopify Plus Integration up and running:

• Install and configure the Loqate app (which you can find here)
  • Basic setup
  • Enabling Address Verify
  • Enabling Email Validation
• Add a checkout block and set Loqate as your address autocompletion provider
• Recommended: include company name

As well as those key actions, there are also some additional steps that you can follow if required:

• Limit Address Capture to specific countries
• Use without Address Capture (not recommended)

Follow these steps in order, and you'll get up and running quickly and easily. If you need help you can contact support@loqate.com.

Installing and configuring the Loqate app

The initial setup will enable Address Capture by default; you can then choose to enable Address Verify and/or Email Validation if you want to use those services too.

Basic setup

First, install the Loqate app from the Shopify App Store (see the Shopify app installation instructions for more details). Once that is done:

• You should automatically be taken to the Admin section for your new Loqate app

• If not, go to accounts.shopify.com, select the Your store option, then select the Loqate app on the left-hand side of the screen to open it

• Copy and paste your Loqate API key in to the API Key field on this screen:

• If you only want to use Address Capture, that's everything you need to do for this stage. You can now click the Save button and skip to the 'Adding Loqate to your Shopify checkout experience' section.
• If you want to use Address Verify and/or Email Validation, carry on with the next section(s).

Address Verify

Address Verify is only available if you're using a Classic platform API key. If you're using a Saas platform API key, the Address Verify section below the API key section will remain greyed out.

If you're using a Classic platform API key, once you've entered your key into the API Key field, the Address Verify section below will become editable:

To add the Address Verify functionality to your checkout, select the Enable address verification option. Once that's done, you can choose the accuracy threshold after which you want Address Verify to autocorrect addresses (see the Address Verify section earlier for more information on thresholds).

If you don't want to use the autocomplete functionality (i.e. Address Verify will suggest alternative addresses but won't automatically make any changes), select the Do not autocorrect addresses option.

If you want to use Email Validation as well, carry on to the next section. If not, click the Save button and move onto the 'Adding Loqate to your Shopify checkout experience' section.

Email Validation

To turn Email Validation on in your checkout, you just need to select the Enable email validation option from the 'Email Validation' section on this page:

Once that's selected, click the Save button and move on to the next section.

Adding Loqate to your Shopify checkout experience

In order for your customers to use Loqate to find and verify their addresses at checkout, you need to customise your checkout page with the "Loqate-Checkout" block (See https://www.shopify.com/enterprise/blog/customize-shopify-checkout). Checkout blocks allow you to customise the look and functionality of your checkout layout and process.

• In the Admin section of your Shopify Plus account, go to Settings > Checkout. From here you can either edit your existing checkout, or create a new draft of your checkout layout.
• To edit your existing checkout click the Customize button, or to create a new draft checkout click the Duplicate button followed by Customize on the new version.

• Next, in the Sections menu of the checkout editor, scroll to the bottom of the page and click Add app block, then select the loqate-checkout app block.

• Finally, in the checkout settings, set Loqate as your provider for Address autocompletion.

• The Loqate checkout extension will now be available on your checkout form. Make sure you save the changes to your checkout, then exit the editor. If you created a new checkout draft, you can click the Publish button to make it live.

Recommended: include company name

By default, Shopify is set to not include a Company name address field. As such, if an address includes a company name (for example if a customer orders a delivery to their place of work) it won't be included in the address that's populated in Shopify.

We recommend setting Shopify to include Company name as an optional address field, so that it will be populated any time an address does include a company name. Here's how to change that setting:

• Go to the site Settings page for your Shopify store 
• Select the Checkout option from the left-hand menu
• Scroll down to the Customer information section

• Set Company name to Optional, then click the Save button

With that done, you should now see an optional Company address field in the checkout:

Optional: Use without Address Capture (not recommended)

We recommend always using Address Capture, as this helps reduce the chances of mistakes caused by manual address entry, ensuring addresses can be trusted as correct and giving the best customer experience. It is, however, possible to use just Address Verification or just Email Validation if you don't want any kind of address autocompletion functionality. 

If you want to use Address Verification and/or Email Validation on their own, follow the full installation and setup process as above, then you can manually disable Address Capture. Here's how to do that:

• First, make sure that you've enabled at least one of Address Verification and/or Email Validation (see the 'Basic Setup' section earlier)
• Then, go to Settings > checkout and click the Customize option for your checkout
• Click on the Settings icon on the left-hand side, then scroll down to the Address autocompletion section

• Untick the Use address autocompletion option, then save the change to your Checkout configuration

This will have disabled the Address Capture functionality, while leaving Address Verify and/or Email Validation running.

Usage

Once the Loqate Shopify app is installed and configured, your customers can start using Loqate's Address Capture service when inputting their addresses. We've put together some screenshots of how that might look on an example checkout page, to give you a sense of what to expect.

Address Capture

Here's what it looks like during an address lookup and after an address has been selected in the Delivery address section:

Address Verify

If you have enabled Address Verify, this functionality will trigger when either the Address or Postcode fields are edited in the Delivery address section.

NOTE: Address Verify is only available for non-logged-in users. Users who have logged into their accounts can instead save addresses and select a saved address to use each time.

If a customer has manually entered an address, here's what that will look like:

If a manually entered/amended address is of a sufficiently low quality, here's the notification that will be generated:

This gives the customer the choice to retain the address if they're happy with it, or re-enter it if not. 

 
Email Validation

If you have enabled Email Validation, this functionality will trigger when a customer enters an invalid email address. Here's what that will look like:

When a customer enters a valid email address, this notification will disappear and they will be able to proceed through the checkout.

Troubleshooting

I can't see some of the Admin options described in this guide

The Loqate Shopify Integration requires a Shopify Plus account. If you don't use Shopify Plus, you won't see all of the necessary options and won't be able to use this integration.

The Capture autocomplete field is not showing on my checkout

Ensure that the API key is correct on the Admin page.

When selecting an address, the fields do not populate

Ensure that your API key is correct on the Admin page, and that you have sufficient credit on your Loqate account.

How do I uninstall the Loqate app?

If you no longer want to use the Loqate Shopify Plus integration, you can uninstall it from your Shopify Plus store.

Please note: if you uninstall the Loqate app and then want to start using it again at a later date, you will need to go through the full installation process again.

To uninstall the Loqate app, go to the Admin page of the app within your Shopify account and click on the three dots at the top-right of the screen. You will see an option to uninstall there:

When you click Uninstall, you'll be prompted to choose a reason for uninstalling:

Select one or more reasons, then click the Uninstall button. This will uninstall the app and return you to the 'Installed Apps' section of your Admin page.

Updating to the latest version - July 2024

The updated version of the Shopify Plus Integration, released in July 2024, provides an updated field layout for a cleaner user experience. 

With this update you'll notice that the 'Search for your address' field, which contained the type-ahead address capture functionality, is no longer present. Instead, the same functionality is now included in the main Address field.

To update to the latest version, first make sure the 'Use address autocompletion' option is selected - we previously advised disabling this, but it now needs to be enabled. Here are the steps to follow in order to do this: 
 
1. Go to the site Settings page for your Shopify store
2. Select the Checkout option from the left-hand menu
3. Click the Customize button next to your checkout
4. Select the Settings icon on the left-hand side
5. Scroll down to the Address autocompletion section and make sure the 'Use address autocompletion' option is checked
6. Click the Save button at the top-right of the screen to save this change
 
With that done, there's a one-click process for migrating to the latest version. In the Admin section for your Loqate app, you'll see a section labelled 'Address Capture Migration' at the top of the screen:

From here just click the Migrate button to upgrade. Once that's done, you'll see a message confirming that you have successfully migrated to the latest version.

To confirm, head to your checkout page where you should see the updated field layout.