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.
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
- Open the Loqate app in your Shopify Admin
- Go to the Advanced Settings page
- Click the Custom Field Mappings link
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, mappingline1 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: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:
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:
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.- Capture source fields
- Verify source fields
Capture source fields come from the Loqate Address Capture (Retrieve) API response.Address lines:
line1, line2, line3, line4, line5Organisation: company, departmentBuilding / premise: subBuilding, buildingName, buildingNumberStreet: street, secondaryStreet, block, neighbourhoodGeographic hierarchy: district, city, adminAreaName, adminAreaCode, province, provinceName, provinceCodePostal: postalCode, pOBoxNumberCountry: countryName, countryIso2, countryIso3Other: domesticId, language, languageAlternatives, sortingNumber1, sortingNumber2, barcode,
field1 through field20Examples
Combine building name and street into Address Line 1
Capture mapping foraddress1:
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 foraddress1:
Uppercase city names
Capture mapping forcity:
LONDON instead of London
Fallback when a field might be empty
Capture mapping foraddress2:
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
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.
Back to Integration Guide
Return to the Shopify Plus Integration Guide for full setup instructions.