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

# Custom Field Mappings

> Configure how Loqate address data maps to Shopify checkout fields, with support for templates, conditional logic, and country-specific overrides.

Custom field mappings give you full control over how address data from Loqate is mapped into Shopify's checkout fields.
By default, the Loqate app uses built-in logic to populate fields such as Address Line 1, Address Line 2, City, and so on.
Custom field mappings allow you to override this behaviour when the default mapping doesn't suit your needs.

<Note>
  Custom field mappings are optional. If you don't configure any, the app continues to use its built-in mapping logic.
  You only need this feature if you want to change how address components are assigned to Shopify fields.
</Note>

## When to use custom field mappings

Common scenarios where custom field mappings are useful:

* **Combining address components** — for example, merging a building name and street into a single Address Line 1 field
* **Country-specific formatting** — some countries have address structures that don't map neatly to Shopify's standard fields
* **Conditional logic** — including or excluding address components based on whether they have values, to avoid empty separators or trailing commas
* **Field transforms** — converting field values to uppercase or truncating long values

## Accessing custom field mappings

1. Open the Loqate app in your Shopify Admin
2. Go to the **Advanced Settings** page
3. Click the **Custom Field Mappings** link

This opens the field mappings editor, where you can configure default mappings and country-specific overrides.

***

## How it works

The field mappings editor has two main sections:

### Default mapping

The default mapping applies to all countries unless overridden by a country-specific mapping. For each Shopify target
field, you choose how to populate it — either by selecting a single source field from a dropdown, or by writing a custom
template for more complex formatting.

You can configure separate mappings for **Capture** (type-ahead address lookup) and **Verify** (post-checkout address
verification), because these two services return different sets of address fields.

### Country overrides

Country overrides let you define mappings that apply only to addresses in a specific country. When a country override
exists, it is used instead of the default mapping for that country. This is useful when certain countries have unique
address formats that require different field assignments.

To add a country override, select the country from the dropdown and click **Add**. You can then configure Capture
and Verify mappings for that country independently.

***

## Shopify target fields

These are the Shopify checkout fields you can map to:

| Field          | Description                 |
| -------------- | --------------------------- |
| `address1`     | Address Line 1              |
| `address2`     | Address Line 2              |
| `company`      | Company name                |
| `city`         | City / Town                 |
| `zip`          | Postal / ZIP code           |
| `countryCode`  | Country code (ISO 2-letter) |
| `provinceCode` | Province / State code       |

***

## Simple field mapping

For straightforward one-to-one mappings, select the source field from the **Source Field** dropdown. This maps a single
Loqate field directly to the Shopify target field. For example, mapping `line1` to `address1` will populate Shopify's
Address Line 1 with the value of the Loqate `line1` field.

***

## Custom templates

For more complex mappings, select **Custom template** from the Source Field dropdown to enter a template string.
Templates use a Handlebars-style syntax that lets you combine fields, add conditional logic, and apply transforms.

### Basic syntax

Insert a field value using double curly braces:

```
{{line1}}
```

Combine multiple fields with literal text between them:

```
{{buildingName}}, {{street}}
```

### Conditional blocks

Use `{{#if}}` to include content only when a field has a value. This prevents empty separators or trailing commas
when optional fields are absent:

```
{{line1}}{{#if line3}}, {{line3}}{{/if}}
```

In this example, if `line3` has a value the output is `123 Main St, Apt 4B`. If `line3` is empty, the output is
simply `123 Main St` — without the trailing comma.

You can also use `{{else}}` for fallback content:

```
{{#if buildingName}}{{buildingName}}{{else}}{{line1}}{{/if}}
```

### Transforms

Apply transforms using the pipe (`|`) character:

| Transform     | Description              | Example                              |
| ------------- | ------------------------ | ------------------------------------ |
| `upper`       | Convert to uppercase     | `{{city \| upper}}`                  |
| `lower`       | Convert to lowercase     | `{{city \| lower}}`                  |
| `truncate N`  | Truncate to N characters | `{{line1 \| truncate 30}}`           |
| `replace A B` | Replace A with B         | `{{line1 \| replace "St" "Street"}}` |

***

## Source fields

The available source fields differ depending on whether you are configuring a **Capture** or **Verify** mapping,
because the two services return different address data structures.

<Tabs>
  <Tab title="Capture source fields">
    Capture source fields come from the Loqate Address Capture (Retrieve) API response.

    **Address lines:** `line1`, `line2`, `line3`, `line4`, `line5`

    **Organisation:** `company`, `department`

    **Building / premise:** `subBuilding`, `buildingName`, `buildingNumber`

    **Street:** `street`, `secondaryStreet`, `block`, `neighbourhood`

    **Geographic hierarchy:** `district`, `city`, `adminAreaName`, `adminAreaCode`, `province`, `provinceName`, `provinceCode`

    **Postal:** `postalCode`, `pOBoxNumber`

    **Country:** `countryName`, `countryIso2`, `countryIso3`

    **Other:** `domesticId`, `language`, `languageAlternatives`, `sortingNumber1`, `sortingNumber2`, `barcode`,
    `field1` through `field20`
  </Tab>

  <Tab title="Verify source fields">
    Verify source fields come from the Loqate Address Verify API response.

    **Delivery address lines:** `deliveryAddress`, `deliveryAddress1` through `deliveryAddress8`

    **Address lines:** `address`, `address1` through `address8`

    **Organisation:** `organization`, `organizationName`, `organizationType`

    **Geographic hierarchy:** `superAdministrativeArea`, `administrativeArea`, `administrativeAreaIso2`,
    `administrativeAreaName`, `administrativeAreaType`, `subAdministrativeArea`, `locality`, `localityName`,
    `localityType`, `dependentLocality`, `dependentLocalityName`, `doubleDependentLocality`

    **Thoroughfare:** `thoroughfare`, `thoroughfareName`, `thoroughfareType`, `thoroughfarePreDirection`,
    `thoroughfarePostDirection`, `dependentThoroughfare`, `dependentThoroughfareName`

    **Building / premise:** `building`, `buildingName`, `buildingType`, `premise`, `premiseNumber`, `premiseType`,
    `premiseExtra`, `subBuilding`, `subBuildingName`, `subBuildingNumber`, `subBuildingType`, `subBuildingFloor`

    **Postal:** `postalCode`, `postalCodePrimary`, `postalCodeSecondary`, `postBox`, `postBoxNumber`, `postBoxType`

    **Country:** `country`, `countryName`, `iSO3166-2`, `iso3166_3`, `iso3166_n`

    **Other:** `sequence`, `contact`, `department`, `floorNumber`, `floorType`, `lotNumber`, `route`, `routeNumber`, `routeType`
  </Tab>
</Tabs>

***

## Examples

### Combine building name and street into Address Line 1

**Capture mapping for `address1`:**

```
{{buildingName}}{{#if street}}, {{street}}{{/if}}
```

**Result:** `Chester Business Park, Wrexham Road` or just `Wrexham Road` if there is no building name.

### Country-specific formatting for Japan

Create a country override for **JP** and set the Verify mapping for `address1`:

```
{{thoroughfare}} {{subBuilding}}
```

### Uppercase city names

**Capture mapping for `city`:**

```
{{city | upper}}
```

**Result:** `LONDON` instead of `London`

### Fallback when a field might be empty

**Capture mapping for `address2`:**

```
{{#if line2}}{{line2}}{{else}}{{#if line3}}{{line3}}{{/if}}{{/if}}
```

Uses `line2` if available, otherwise falls back to `line3`.

***

## Validation

The app validates your templates when you save. Common validation errors include:

* **Invalid field names** — only recognised source fields (listed above) can be referenced in templates
* **Malformed template syntax** — unclosed `{{#if}}` blocks or mismatched braces
* **Template too long** — templates have a maximum length to prevent unexpected behaviour

If validation fails, you'll see an error message describing the issue. Fix the template and save again.

***

## Tips

* Start simple. Use one-to-one field mappings where possible and only use custom templates when you need conditional
  logic or field combination.
* Test with real addresses. After saving your mappings, run through the checkout with addresses from the countries
  you've configured to verify the output looks correct.
* Country overrides take precedence. If both a default mapping and a country override exist for a given country,
  the country override is used and the default is ignored entirely for that country.
* Capture and Verify are independent. You can configure custom mappings for Capture only, Verify only, or both.
  Whichever service doesn't have a custom mapping will continue using the built-in logic.

***

<Card title="Back to Integration Guide" href="/integrations/shopify-plus-overview">
  Return to the Shopify Plus Integration Guide for full setup instructions.
</Card>