> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loqate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Setup Guide

> Install Loqate in your Shopify checkout in minutes. Subscribe through Shopify or connect an existing account, then enable Address Capture, Address Verify, and Email Validation.

In this guide we will provide all of the information you need to get up and running using the Loqate Shopify Integration:
setting up the app, adding each Loqate service to your checkout, managing your settings, and handling your subscription and
usage cap.

If you're looking for the full details of what the Loqate Shopify Integration does, what runs on your Shopify plan, how
subscriptions work, and what it looks like in practice, you can find that here:

> [card] [Shopify Integration in Practice](https://docs.loqate.com/integrations/shopify-plus-integration-in-practice.md)
>
> What the app does, what works on your Shopify plan, and how subscriptions and usage caps work.

## Setup Video

[YouTube video player](https://www.youtube.com/embed/y4_Brz0DOIk)

***

## Choose your setup route

How you set up the app depends on how you came to Loqate:

| You are | Use this route | Where you are billed |
| - | - | - |
| A Shopify merchant who found Loqate in the Shopify App Store | [Set up Loqate as a new customer](#set-up-loqate-as-a-new-customer), using Shopify billing | Shopify |
| An existing Loqate customer | [Connect an existing Loqate account](#connect-an-existing-loqate-account), using an API key from your Loqate account | Loqate |

If you are new to Loqate and coming from the Shopify App Store, subscribe through Shopify — you don't need to create a
Loqate account or an API key first, because the app sets up your account for you. If you already have a Loqate account,
created the standard way at [account.loqate.com](https://account.loqate.com/), connect it with an API key from that
account instead.

## Prerequisites

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

* A Shopify store. The app installs on any Shopify plan, but your plan decides which Loqate services you can use. See
  [what works on your Shopify plan](https://docs.loqate.com/integrations/shopify-plus-integration-in-practice.md#what-works-on-your-shopify-plan).
* A checkout that is not password protected, if you want to use the order confirmation page.

If you are subscribing through Shopify:

* You need permission to approve app charges for your store.
* Have a few minutes spare at the end, while your account is set up.

If you are an existing Loqate customer:

* You need a live Loqate account at [account.loqate.com](https://account.loqate.com/).
* You need an API key from that account (see the API keys section below).

### API keys

You only need an API key if you are an existing Loqate customer. If you subscribe through Shopify, the app sets up your
Loqate account for you once you approve your plan.

Create the key in your Loqate account. Our [Creating API Keys page](https://docs.loqate.com/loqate-basics/create-an-api-key.md) explains how to do
this. We recommend you create a generic API key dedicated to this service, but any key will work.

**Note** You use Address Capture, Address Verify and Email Validation from a single API key.

For information about how to ensure your Loqate integration is as secure as possible, see our
[API Security page](https://docs.loqate.com/loqate-basics/api-security.md).

***

## Installation

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

* Install the Loqate app, then either [set up Loqate as a new customer](#set-up-loqate-as-a-new-customer) or
  [connect an existing Loqate account](#connect-an-existing-loqate-account)
* [Enable Address Capture, Address Verify and Email Validation](#enabling-loqate-services)
* [Recommended - include company name](#recommended-include-company-name)

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

* [Use without Address Capture (not recommended)](#optional-use-without-address-capture-not-recommended)
* [Advanced Settings (optional)](#optional-advanced-settings)

Follow these steps in order, and you'll get up and running quickly and easily. If you need help you can
contact [LoqateSupport@GBG.com](mailto:LoqateSupport@GBG.com).

### Set up Loqate as a new customer

Follow this route if you found Loqate in the Shopify App Store and your store has no Loqate account yet. You subscribe and
pay through Shopify's billing. At the end you will have an active subscription and a working Loqate settings screen.

**1. Install the Loqate app**

Install [the Loqate app](https://apps.shopify.com/loqate) from the Shopify App Store. The
[Shopify app installation instructions](https://help.shopify.com/en/manual/apps/installing-apps)
explain how installing an app works.

**2. Open Loqate in your Shopify admin**

In your Shopify admin, open **Loqate** under **Apps**. The **Welcome to Loqate** screen opens.

![Welcome screen](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-welcome-screen.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=8c9c66e47ea9af4461980edfae29211c)

**3. Tell Loqate you are new**

Select **I'm new to Loqate**, then select **Continue**.

**4. Accept the terms and conditions**

Select **Open the agreement in a new tab** and read the Loqate End User Licence Agreement. Return
to the app, tick **I accept the Terms and Conditions**, then select **Continue**.

![Terms and Conditions](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-t-and-c.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=7dc1928fb94b47ff595dafa82303f342)

**5. Choose your plan**

On **Choose your subscription**, select the plan whose monthly usage cap suits your store, then
select the approve button for that plan. If no plan is large enough, select **Need a higher cap?**
to [ask for a custom plan](#ask-for-a-higher-usage-cap).

![The Choose your subscription screen, showing plan cards with a monthly usage cap and a credit pack size](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-credit-pack.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=2973663b1a9146e6762aac1e1473e552)

[Subscriptions and usage caps](https://docs.loqate.com/integrations/shopify-plus-integration-in-practice.md#subscriptions-and-usage-caps)
explains how plans, caps and credit packs work.

**6. Approve the charge in Shopify**

Shopify opens its own billing screen. Confirm your payment details and approve the subscription.
Shopify then returns you to Loqate.

**7. Wait for activation, then open settings**

Loqate sets up your account. **Go to settings** stays unavailable until **Status** reads
**Activated**, which usually takes a few minutes. Nothing is needed from you while you wait.

![The subscription outcome screen showing the plan, usage cap, an Activated status and the Go to settings button](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-subscription-activation.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=60cbf9b1ee1c6023aa1e7be7ef4e62da)

When **Go to settings** becomes available, select it.

You are set up when the Loqate settings screen opens. From now on, selecting **Loqate** in your
Shopify admin takes you straight there. Next, [enable the Loqate services](#enabling-loqate-services) you want to use.

#### If activation does not finish

If the app is still setting up after five minutes, it offers **Check again**. If Shopify declines the
charge, the app asks you to check your store's billing details in Shopify and try again. In both
cases you can select **Contact support** to reach the Loqate team.

### Connect an existing Loqate account

Follow this route if you are an existing Loqate customer. Your account is created the standard way at
[account.loqate.com](https://account.loqate.com/), and you connect your Shopify store with an API key from that account,
so your billing stays with Loqate and you do not take out a Shopify subscription.

**1. Get an API key from your Loqate account**

Sign in to [account.loqate.com](https://account.loqate.com/) and create an API key, as described in
[API keys](#api-keys) above.

**2. Install the Loqate app**

Install [the Loqate app](https://apps.shopify.com/loqate) from the Shopify App Store.

**3. Open Loqate in your Shopify admin**

In your Shopify admin, open **Loqate** under **Apps**. The **Welcome to Loqate** screen opens.

**4. Tell Loqate you are an existing customer**

Select **I already use Loqate**. An **API key** field opens.

**5. Enter your API key**

Paste your Loqate API key into the field, then select **Use this key**. Keys look like
`WA99-MC49-DU84-ZG25`, or like a 36-character identifier such as
`0f8fad5b-d9cb-469f-a165-70867728950e`. If the key is not in one of those shapes, the app reports
**The API key entered isn't in a known format** and stays on this screen.

The settings screen opens once the key is accepted, and the **Authentication** card reports **Your
Loqate API key is connected**. Next, [enable the Loqate services](#enabling-loqate-services) you want to use.

> [!NOTE]
>
> Address Verify is not available with a Loqate SaaS platform key. If you connect one, both Address
> Verify options are unavailable and the settings screen says why.

#### What is different from a Shopify subscription

| | Connected with your own key | Bought through Shopify |
| - | - | - |
| Where you are billed | Loqate | Shopify |
| Usage allowance | Set by your Loqate account | Your monthly usage cap |
| Managed from | [account.loqate.com](https://account.loqate.com), through **Open account & plan** on the settings screen | The Loqate settings screen |

Your settings screen shows the **Authentication** card rather than a subscription cap, because there
is no Shopify subscription to report.

#### Change your API key

On the settings screen, the **Authentication** card shows your key masked. Select **Show API key** to
reveal it, or **Use a different key** to replace it.

### Enabling Loqate services

> [tab] Enabling Address Capture
>
> > [!NOTE]
> >
> > Address Capture in the checkout, and the Custom Capture Search Input, need a Shopify Plus store. On Basic, Grow and
> > Advanced, customers can still pick a verified address after the order is placed (see
> > [Advanced Settings](#optional-advanced-settings)).
>
> With the app set up, the Standard Address Capture is automatically available. We however
> recommend adding the Custom Capture Search Input as it offers an improved experience when
> searching sub-building addresses.
>
> ![Custom Capture Search 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-containers-1.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=72e46985eb189e77627d41485d85aecb)
>
> First, you need to add the **Loqate-Checkout** app block to your store on the Checkout page.
> (see [https://www.shopify.com/enterprise/blog/customize-shopify-checkout](https://www.shopify.com/enterprise/blog/customize-shopify-checkout)).
> App blocks allow you to customise the look and functionality of your checkout layout. This block is required in order to
> use the Custom Capture Search Input on the Checkout page. Here's how to add this block:
>
> 1. 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
>
> 2. Next, select the Apps icon (the bottom icon) in the left-hand menu of the checkout editor, then search for 'Loqate'
>
> 3. Select the **loqate-checkout** app, then click the plus button and select **Checkout** from the drop-down list - this adds the
>    app block to the Checkout page
>
> 4. Next the [Standard Address Capture search must be disabled.](https://docs.loqate.com/integrations/shopify-plus-setup-guide.md#optional-use-without-address-capture-not-recommended)
>    This will not turn off Capture entirely. Capture will now only run in the app block added using the instructions above. If the standard search is left enabled,
>    Capture address searches will happen in two places on the checkout page (in the custom search input as well as the address text input)
>
> 5. With that done, make sure to 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.
>    > [!WARNING]
>    >
>    > Only stores which are not password protected will successfully allow app
>    > blocks to be added. If the site is password protected, please disable this
>    > before adding.
>
> The final step is to enable the Custom Capture Search Input in the Loqate app. Select **Advanced Settings** in the Loqate app's menu,
> tick **Display a custom Loqate address capture input on the checkout page**, then select **Save** in the **Unsaved changes** bar.
> Note that the custom input cannot search for a billing address. Please test and check that on checkout a new address search
> input has been added above the address form and addresses become available when searching addresses there. It's best practice to test these changes in a lower environment before going to production if possible.
>
> If continuing with the Classic Capture Search which places the address dropdown in the default address text input there is, however, an additional step to make sure Address Capture
> is added to your checkout. Here are the steps to follow:
>
> * 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.
>
>   ![Duplicate Checkout](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-duplicate-checkout.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=cbda52a541ca431caeaebca4c22383d6)
>
> * Once you're editing your checkout, go to the Settings menu (the cog icon on the left-hand side), scroll down to the
>   **Address autocompletion** section and select the **Loqate** option to set Loqate as your provider:
>
>   ![Address Autocompletion](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-address-autocompletion.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=b44cc7c788566bbee3f31924ada08b2d)
>
> * 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.
>
> Address Capture will now be available on your checkout. If you also want to enable Address Verify and/or Email Validation,
> carry on through the Address Verify and Email Validation tabs.

> [tab] Enabling Address Verify
>
> There are a few steps required to enable Address Verify functionality on your checkout. The post checkout option works on
> Basic, Grow, Advanced and Plus stores; the checkout option needs Shopify Plus.
>
> First, you need to add the **Loqate-Checkout** app block to your store
> (see [https://www.shopify.com/enterprise/blog/customize-shopify-checkout](https://www.shopify.com/enterprise/blog/customize-shopify-checkout)).
> App blocks allow you to customise the look and functionality of your checkout layout and process, and this block is required in order to
> use Address Verify on the Thank You (order confirmation) page. Here's how to add this block:
>
> * In the Admin section of your Shopify store, go to Settings > Checkout. From here you can either edit your existing checkout,
>   or create a new draft of your checkout layout (see the Address Capture section above for more details)
>
> * Next, select the Apps icon (the bottom icon) in the left-hand menu of the checkout editor, then search for 'Loqate'
>
> * Select the **loqate-checkout** app, then click the plus button and select **Thank you** from the drop-down list - this adds the
>   app block to the Thank You page
>
>   ![Add App Block](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-add-app-block-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=de252ca096d45b70e698b9b83101289b)
>
> * With that done, 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.
>
> > [!WARNING]
> >
> > Only stores which are not password protected will successfully allow app blocks to be added. If the site is password protected, please disable this before adding.
>
> The next step is to disable the default address verification by Shopify. If this is left enabled, additional suggestions may be
> displayed against individual address fields, which can cause confusion for customers.
>
> * Still in Settings > Checkout, scroll down to the **Address collection preferences** section:
>
>   ![Address Collection](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-address-collection-small.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=13ae16e7b6419658ce371d50d6455526)
>
> * Make sure the **Validate shipping address** option is unticked, then click the Save button
>
> The final step is to enable Address Verify on the Loqate settings screen.
>
> Once your subscription is activated or your API key is connected, the **Address Verify** card on the settings screen becomes
> editable. It has three options, and you choose one:
>
> ![Address Verify options](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-address-verify-options.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=ba482275d799f7865356b470b65845f7)
>
> * **Disable address verification** turns Address Verify off in the checkout and on the order confirmation page
> * **Enable address verification for post checkout (recommended)** checks the address after the order is placed, on the
>   order confirmation page
>   * NOTE: to use the post checkout option, please ensure your store is not
>     [password protected](https://help.shopify.com/en/manual/online-store/themes/password-page)
> * **Enable address verification for checkout (use with caution)** checks the address during the checkout, before the order
>   is placed. This is not recommended because it consumes Verify transactions during checkout (including abandoned checkouts),
>   and it only runs on Shopify Plus stores. See the note below.
>
> Select **Save** in the **Unsaved changes** bar, and Address Verify will now be available.
>
> > [!NOTE]
> >
> > Address Verify is not available with a Loqate SaaS platform key. If your store is connected with one, both enabled options
> > are greyed out and the settings screen says so.
>
> > [!NOTE]
> >
> > **Address Verify on the checkout page ("Enable address verification for checkout")**
> >
> > Use this option with caution. When Address Verify runs on the checkout page (rather than after checkout), the customer's address is verified while they are still completing their order.
> >
> > This has a few important implications:
> >
> > * It uses Verify transactions during checkout. Every address that reaches the verification step is checked against Loqate Verify and counts towards your usage — including checkouts that customers later abandon before placing an order. The post checkout option only verifies the address once the order has actually been placed, so it typically results in fewer Verify requests and more predictable usage.
> > * It does not work with express / wallet payments. Apple Pay, Google Pay, Shop Pay, PayPal and similar express checkouts bypass the standard address form, so Address Verify cannot run for those orders and the customer will not be prompted to correct their address.
> > * It adds a step to the checkout flow. Because verification happens before the order is placed, customers may be asked to confirm or correct their address as part of completing checkout.
> > * It needs a Shopify Plus store. Shopify reserves the checkout steps for Shopify Plus, so this option does not run on Basic, Grow or Advanced stores.
> >
> > For most stores we recommend the **Enable address verification for post checkout** option, which verifies the address after the order is placed and avoids the points above. Only enable verification on the checkout page if you specifically need the address corrected before the order is created and you understand the additional Verify usage this can incur.

> [tab] Enabling Email Validation
>
> > [!NOTE]
> >
> > Email Validation runs in the checkout email field, so it needs a Shopify Plus store.
>
> The steps to enable Email Validation in your checkout are similar to those for Address Verify.
>
> First, add the **Loqate-Checkout** app block to your store (if it hasn't already been added by the Capture installation) - It needs to be added to the **Checkout** section.
>
> * 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 (see the Address Capture section above for more details)
> * Select the Apps icon (the bottom icon) in the left-hand menu of the checkout editor, then search for 'Loqate'
> * Select the **loqate-checkout** app, then click the plus button and select **Checkout** from the drop-down list
>
>   ![Add App Block 2](https://mintcdn.com/loqate/9_Nppb2BEMzsAUI3/images/integrations/shopify-plus/shopify-add-app-block-2-june-25.png?fit=max\&auto=format\&n=9_Nppb2BEMzsAUI3\&q=85\&s=0d11ce8c547a25bb7d479c3a669c4006)
>
> Once that's done, you just need to turn on the **Email Validation** switch on the Loqate settings screen.
>
> Once that's done, select **Save** in the **Unsaved changes** bar and move on to the next section.

***

### 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

![Company Name Settings](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-company-name-settings-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=ccd1dd782c35c4ed29de31907c3528f5)

* 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:

![Company Name 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-company-name-1-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=c47adb99270a36a4985a1d0dc16a3fb9)

***

### 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 [Enabling Loqate services](#enabling-loqate-services)
  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

![Address Autocompletion](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-verify-1-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=cefb80bdc8491f0d8fd11c15c3fb7bd7)

* 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.

***

### Optional - Advanced Settings

Select **Advanced Settings** in the Loqate app's menu to open the Advanced Settings page. It includes the following optional
settings, as well as the **Display a custom Loqate address capture input on the checkout page** option described in the
[Address Capture](#enabling-loqate-services) tab above. Select **Save** in the **Unsaved changes** bar after making a change.

> [accordion] Force addresses to be returned in latin character sets where available
>
> With this selected, Address Capture will always attempt to use any English results to set the delivery address, even with non-latin
> results. Note that for this setting to work, the **Display a custom Loqate address capture input on the checkout page** option
> must be **enabled**.
>
> For example, here's a Japanese address searched for using Kanji characters:
>
> ![Non-Latin 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-non-latin-1.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=a66afa2d3bb464c86b3898d97561c1c3)
>
> And here's the result populated using the English version of the address:
>
> ![Non-Latin 2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-non-latin-2.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=9918afbf3932b99d95b2557cda8f87b5)
>
> This is useful for when carriers have difficulty processing non-latin addresses.

> [accordion] Use address capture to allow customers to update their address if the shipping address cannot be verified
>
> With this enabled, customers can manually amend their addresses post-checkout, if what they initially entered can't be verified.
> This runs on the order confirmation page, so it works on Basic, Grow, Advanced and Plus stores.
> For example, if a customer hasn't entered their building number or apartment number they can go back and add it in.
>
> Under these circumstances, after an order has been confirmed the customer will be presented with a list of possible addresses to
> choose from:
>
> ![Post Checkout Verify 1](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-post-checkout-verify-1.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=23efc21483cc4300c72e63aa5b14bfd5)
>
> If the customer selects one of the suggested addresses, they will then see a notification acknowledging the address they've selected
> and giving them the option to update their shipping address:
>
> ![Post Checkout Verify 2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-post-checkout-verify-2.PNG?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=06f7c6ec392f1a2f6ba15e0150fca60c)

> [accordion] Use enhanced country validation on unverified addresses
>
> Sometimes it can be possible for a customer to enter an address with the wrong country, which as standard will be flagged as an
> unverified address.
>
> Selecting this option enables Address Verify to be automatically called for a second time whenever an address is returned as unverified.
> For the second call, Address Verify will run using enhanced country verification, providing another opportunity to verify the address
> with the correct country.
>
> For this to function Address Verify must be enabled on the **Thank you** page. This functionality uses an extra Verify transaction
> for each second check, which counts towards your usage cap or Loqate account usage.

> [accordion] Custom field mappings
>
> Custom field mappings allow you to control how Loqate address data is mapped into Shopify's checkout fields. By default, the app uses
> built-in logic to populate fields like Address Line 1, Address Line 2, City, and so on. With custom field mappings, you can override
> this behaviour — either globally or on a per-country basis — to handle address formats that don't fit the default mapping.
>
> This is useful when you need to combine multiple address components into a single Shopify field, apply conditional logic based on
> whether certain fields have values, or handle country-specific formatting requirements.
>
> To configure custom field mappings, select **Manage field mappings** in the **Custom field mappings** summary on the Advanced Settings page. For full details on how
> to set up and use this feature, see the dedicated guide:
>
> > [card] [Custom Field Mappings Guide](https://docs.loqate.com/integrations/shopify-plus-custom-field-mappings.md)
> >
> > Learn how to configure custom field mappings with template syntax, country overrides, and examples.

***

## Manage your Loqate settings

The settings screen is where you turn Loqate services on and off and check your subscription. Open it
by selecting **Loqate** under **Apps** in your Shopify admin.

![Shopify Settings Screen for New Loqate Users with subscription](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-settings-screen.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=cf1c17cfcdb651e3972b2c233c942d99)

### What is on the screen

| Card | What it is for |
| - | - |
| Subscription | Your usage cap, your API key, or a prompt to buy a subscription. The card you get depends on how your store pays for Loqate. |
| **Loqate services** | A summary of Address Capture, Address Verify and Email Validation. Nothing to set here. |
| **Address Verify** | Choose one of the three verification options. |
| **Email Validation** | Switch email checking on or off. |

The page header also carries **Open integration guide**, which opens this documentation.
[Loqate services in your checkout](https://docs.loqate.com/integrations/shopify-plus-integration-in-practice.md#loqate-services-in-your-checkout)
explains what each Address Verify option does before you choose one.

### Your subscription card

The screen shows one of three subscription cards, chosen from your store's own records.

| Your situation | What you see | What you can do |
| - | - | - |
| You have a Shopify subscription | **Current subscription cap** and your monthly figure | Select **Change cap** to move to a different plan |
| Your Shopify subscription has ended | **No subscription**, with the message that your subscription has ended | Select **Choose a subscription** to buy one |
| You pay Loqate directly | **Authentication**, with your API key masked | Select **Show API key**, or **Use a different key**. **Open account & plan** opens your Loqate account |

If the card reads **Cap unavailable**, Shopify could not report your cap at that moment. Your
subscription is unaffected and **Change cap** still works. Refresh the page to try again.

### Save a change

The save bar appears at the top of the screen as soon as you edit a setting, and it is the only way
to save.

1. Change a setting.
2. Select **Save** in the **Unsaved changes** bar, or **Discard** to undo your edits.

If you leave the screen with unsaved changes, the app asks whether to **Leave page** or **Stay**.

***

## Change your usage cap

Move to a different plan when your store needs more or less monthly allowance. This applies to stores
subscribed through Shopify; if you connected your own API key, manage your allowance in your Loqate account.

1. Open the Loqate settings screen.
2. On the subscription card, select **Change cap**. The **Change your subscription cap** screen opens.
3. Select the plan whose monthly usage cap suits your store. If no plan is large enough, select
   **Need a higher cap?** to [ask for a custom plan](#ask-for-a-higher-usage-cap).

A higher cap is available straight away. A lower cap can wait until your next billing cycle — see
[renewal and cap changes](https://docs.loqate.com/integrations/shopify-plus-integration-in-practice.md#renewal-and-cap-changes).

## Ask for a higher usage cap

If none of the plans on offer has a large enough monthly usage cap, use the contact form in the app
to ask for a custom plan. Have an idea of the cap you need and how many orders your store processes
in a month. The Loqate team uses both to work out a plan for you.

### Send a request

**1. Open the contact form**

On **Choose your subscription** or **Change your subscription cap**, select **Need a higher cap?**.

![Contact screen](https://mintcdn.com/loqate/wa5smTsue6eCAxOJ/images/integrations/shopify-plus/shopify-contact-screen.png?fit=max\&auto=format\&n=wa5smTsue6eCAxOJ\&q=85\&s=08e6b8256bacd7f53dbc1abf56b98841)

**2. Check your details**

**Shop domain**, **Your name** and **Email address** are filled in from your Shopify account.
**Shop domain** cannot be edited. Correct your name or email address if they are wrong, because
the reply goes to the email address on the form.

**3. Choose a topic**

**Topic** is already set to **Higher usage cap**. The other options are **Billing question**,
**Technical issue** and **Other**.

**4. Describe what you need**

In **Tell us more**, say what cap you are looking for and how many orders you process a month.
**Send message** stays unavailable until you write something.

**5. Send it**

Select **Send message**.

A **Message sent** banner confirms the request, and the Loqate team replies to the email address on
the form. Select **Back to plans** to return to the plans you came from, or **Cancel** to go back
without sending.

### If the message does not send

The screen reports **Message not sent** when it cannot reach Loqate. The **Call us** card on the same
screen lists a phone number and the hours the team is available, and calling gets you a faster answer
than the form.

## Cancel and restart your subscription

Cancel a Loqate subscription from the Shopify admin, in the same place you manage your other app
charges. Your subscription stays active until the end of the billing period you have paid for, then
it does not renew.

After it ends, the Loqate settings screen shows **No subscription**. The app stays installed, but the
services need an active subscription to run. To start again, select **Choose a subscription** and
pick a plan. Your access is restored once the new subscription is approved and activated.

***

## Troubleshooting

> [accordion] I can't see some of the Admin options described in this guide
>
> The app installs on any Shopify plan, but Shopify reserves the checkout steps for Shopify Plus stores. If you don't use Shopify Plus,
> you won't see the checkout editor options for Address Capture, Email Validation or the Address Verify checkout option. The post
> checkout features on the order confirmation page still work on Basic, Grow and Advanced. See
> [what works on your Shopify plan](https://docs.loqate.com/integrations/shopify-plus-integration-in-practice.md#what-works-on-your-shopify-plan).

> [accordion] My subscription is still activating
>
> Activation usually takes a few minutes. See [if activation does not finish](#if-activation-does-not-finish).

> [accordion] The Capture autocomplete field is not showing on my checkout
>
> Checkout autocomplete needs Shopify Plus; on Basic, Grow and Advanced it will not appear even with an active subscription or connected key. On Shopify Plus, check that your subscription shows as active on the Loqate settings screen, or, if you connected your own key, that the **Authentication** card reports **Your Loqate API key is connected**.

> [accordion] When selecting an address, the fields do not populate
>
> Check that your subscription is active and that you have not used up your monthly usage cap. If you connected your own key, check
> that your API key is correct on the **Authentication** card and that you have sufficient credit on your Loqate account. If you need
> more allowance, [change your usage cap](#change-your-usage-cap).

> [accordion] How do I uninstall the Loqate app?
>
> If you no longer want to use the Loqate Shopify integration, you can uninstall it from your Shopify 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:
>
> ![Uninstall](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-uninstall-june-25.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=23898b227eae9ff0ff619ac7e561b9d8)
>
> When you click **Uninstall**, you'll be prompted to choose a reason for uninstalling:
>
> ![Uninstall 2](https://mintcdn.com/loqate/sKY9PIVDXiacbW-t/images/integrations/shopify-plus/shopify-uninstall-2.png?fit=max\&auto=format\&n=sKY9PIVDXiacbW-t\&q=85\&s=3c38e422e6f3e51ea836a47ca8b7df53)
>
> 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.

***

> [card] [Further reading](https://docs.loqate.com/integrations/shopify-plus-integration-in-practice.md)
>
> If you haven't already, check out our 'Shopify Integration in Practice'
> article for what runs on your Shopify plan, how subscriptions and usage caps
> work, and examples of the integration in use.
