Works with:

Oracle Cloud Infrastructure (OCI)

Supported Loqate Services:

Address Verify

Integrate in 3 steps ``` As you can see the controls are included like this: ```apex theme={null} ``` You may need one, or as in this case multiple instances of the control for your page. The attributes for this component are as follows: | Attribute name | Description | Example | | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------- | | label | This is the label for the control, and will appear alongside the control input box on pages. | Mailing Address | | namespace | Optional. This attribute is important when you have multiple controls on a single page, as this allows the controls to operate independently of each other. It must be unique across rendered controls. | mailing | | onAddressSelectedFunction | This should be set to the name of the callback function that selected addresses will be returned to. | handleMailingAddressSelected | | Mapping | Optional. If a mapping group name is provided, the second argument passed to the callback function will be an object whose keys and values are those of the mapped fields. | Contact Mailing | Let's look in more detail at some of the aspects of the callback function and how the data gets into a record. The page itself (as well as using Lightning stylesheets to give a Lightning look and feel) uses the standard Contact controller: ```apex theme={null} ``` This allows it to act as a creation form for the standard Contact object. This in turn means that you can set values against the Contact records properties within the page. For the first and last name fields, this is achieved by binding the field to the FirstName and LastName fields of the controller: ```apex theme={null} ``` However, for the address lookups controls this is a little more involved. You can’t map directly from JS to the values, so instead you expose the properties you want to set via a selection of hidden inputs: ```apex theme={null} ``` You can then declare a callback function for each of the address lookups on the page. These fill take the address output of the lookup, and push it into the record fields defined above: ```apex theme={null} ``` Finally, you can add a command button that will call the Save function on the standard controller: ```apex theme={null} ``` The response to this button press off a standard controller is to redirect to the record, so that flow is taken care of. ### Using the page in place of the standard New view With a Visualforce page in place that uses the Address Capture components, you now need to override the default behaviour of the New button on the contact listing page. This is achieved through the Object Manager, so navigate to Setup and search for Object Manager. Once there, select **Contact** from the list.

Next select **Button, Links and Actions** from the left-hand menu, then edit the **New** action – you should be able to select the new page from the **Visualforce** page dropdown field:

Click **Save**, and from now on the New action on the contact listing page will open your new page, and you can create contacts with verified addresses. # Custom Field Mappings Source: https://docs.loqate.com/integrations/shopify-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. 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 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. 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` 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` *** ## 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. *** Return to the Shopify Plus Integration Guide for full setup instructions. # Verify Shopify Customer Data in Seconds Source: https://docs.loqate.com/integrations/shopify-overview Native Shopify Plus integration with Address Capture, Address Verify, and Email Validation. Improve checkout data quality.

Works with:

Shopify Plus Checkout

Supported Loqate Services:

Address Capture
Address Verify
Email Verification

Integrate in 3 steps ``` **NOTE:** minified versions of these files are available. To use them, update the above snippets with .min before the file type (i.e. .../address-4.05.min.css and .../address-4.05.min.js). ## Mapping your fields The address capture control needs to know which elements of the address should be put into each of your fields. It also needs to know which fields should be used for searching and which field (if any) contains the country. This information is provided in a standard format, which is an array of objects that have an **element**, **field** and optional **mode** property. ```javascript theme={null} var fields = [ // Search field - triggers autocomplete when user types { element: "search", field: "" }, // Company - preserves existing value if already populated by user { element: "company", field: "Company", mode: pca.fieldMode.DEFAULT | pca.fieldMode.PRESERVE }, // Address lines - Line1 uses default behavior (SEARCH + POPULATE) { element: "line1", field: "Line1" }, // Line2 and subsequent fields only populate, don't trigger search { element: "line2", field: "Line2", mode: pca.fieldMode.POPULATE }, { element: "city", field: "City", mode: pca.fieldMode.POPULATE }, { element: "state", field: "Province", mode: pca.fieldMode.POPULATE }, // Postal code field { element: "postcode", field: "PostalCode" }, // Country field - displays country list on focus and sets search context { element: "country", field: "CountryName", mode: pca.fieldMode.COUNTRY } ]; ``` ### Field Configuration Properties * **element**: The id or name attribute of your field. Accepts partial id match (e.g., "\_line1" matches "frm1\_line1") or JavaScript regex for complex matching. * **field**: The name of the address element for this field. See [Capture Interactive Retrieve](#security) for available fields. Also accepts format strings (detailed in next section). * **mode**: Controls field behavior. Default is **SEARCH** and **POPULATE**. Modes are declared in **pca.fieldMode** and can be combined using bitwise OR (|): * **SEARCH**: Enables autocomplete searching from the field * **POPULATE**: Sets the field value based on selected address * **COUNTRY**: Displays country list on field select and reads field value to set search country * **PRESERVE**: Prevents overwriting fields already populated by user (useful for company name) ## Formatting fields To define complex or custom field values, the control makes use of template strings. The template strings work by replacing field values from the selected address, based on field names which are enclosed in curly brackets, for example `{PostalCode}`. Any regular text or HTML can be included in the template strings around the field values, such as `{Line1}, {Line2}`. Conditional formatting can be added by enclosing the field, and any additional text which is conditional on the field having a value, in a second set of curly brackets. If the template string was `{Line1}{, {Line2}}` then the comma would not appear unless the selected address had a second address line. Finally, field values will always appear in title case, but can easily be capitalised by adding an exclamation mark (!) at the end of the field name, like this `{City!}`. ## Setting options The second parameter that is required by the address control is a configuration object. This is used to set options and customise how the control behaves. The only required option is the API key that you will be using to access the web services, and is defined by creating an object literal in JavaScript. ```json theme={null} { key: "AA11-AA11-AA11-AA11" } ``` Further options can be set by adding more information to the configuration object. To create a control that was limited to the United States and Canada, but set the country based upon the users IP address, you would define the following object: ```json theme={null} {key: "AA11-AA11-AA11-AA11", countries: { codesList:"USA,CAN"}, setCountryByIP: false} ``` ## Countries Capture+ is designed to be a truly international address verification and standardisation solution, and will by default allow you to search through all of the [countries that are covered](https://www.loqate.com/en-gb/address-verification/). However, you can limit the countries that Capture+ will search by adding search settings into your options object. For example, to create a control that was limited to the United States and Canada, but set the country based upon the users IP address, you would define the following object: ```json theme={null} {key: "AA11-AA11-AA11-AA11", countries: { codesList:"USA,CAN"}, setCountryByIP: false} ``` ## Geolocation options (Available only for UK addresses) Loqate's address capture also supports address lookup based on your end user's current location. In order to access this additional functionality, you will have to add the following to your options object: `GeoLocationEnabled`: true, `GeoLocationRadius`: 50, `GeoLocationMaxItems`: 10 These attributes are defined as follows: * `GeoLocationEnabled`: Boolean to determine if the Geolocation functionality is active * `GeoLocationRadius`: Integer to determine the radius of the requested search in metres * `GeoLocationMaxItems`: The number of results to display in the dropdown You also need your site to run under https to enable this functionality. This will add an additional item to the address capture bar, allowing your user to search for their address based on their current location. An example of the complete options object is as follows: ```json theme={null} { key: "AA11-AA11-AA11-AA11", search: { countries: "GBR" }, setCountryByIP: true, GeoLocationEnabled : true, GeoLocationRadius : 50, GeoLocationMaxItems : 10} ``` Note: "GBR" is the ISO 3166-1 alpha-3 country code for the United Kingdom. Geolocation is currently available only for UK addresses, so when using `GeoLocationEnabled` you must include "GBR" in the `countries` setting. ## Language Both the control and web service API support a variety of language cultures. The language is automatically detected from the user's web browser but a **culture** option and **setCulture** method are also provided. The culture is based on 2-character code (e.g. "en", "fr") or culture name (e.g. "en\_GB", "en\_US", "fr\_FR", "fr\_CA"). ## The control object When you instantiate a new **pca.Address** object you will get a reference to an object commonly referred to as the **control** object. ```javascript theme={null} var control = new pca.Address(fields, options); ``` This is the main object for address capture on your address form and provides all methods and properties to customise the address capture experience. You will typically have one of the these objects for each of your address forms, so it is important to give them individual references or store them in a list. ```javascript theme={null} var billingControl = new pca.Address(billingFields, billingOptions); var shippingControl = new pca.Address(shippingFields, shippingOptions); ``` The control object will automatically wait for the page DOM to be loaded before it initialises, so it is important to listen for the **load** event before calling methods on the control object. ```javascript theme={null} var control = new pca.Address(fields, options); control.listen("load", function() { control.setCountry("CAN"); }); ``` ## Events and listeners The address capture library implements a simple events model which will allow you to listen out for when certain things happen. To listen for an event use the **listen** method with the event name and a function to run when that event occurs. Events can sometimes pass additional details through parameters. ```javascript theme={null} control.listen("populate", function(address, variations) { document.getElementById("myCustomField").value = address.PostalCode; }); ``` The key events to listen for are: | Event | What it means | | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | load | The control is now ready. It has finished adding elements to the page and is now listening to page events. | | show | The control is now visible on the page. | | hide | The control has been hidden. | | search | The user is searching. You can modify the **searchTerm** and **lastId** of the search object (parameter 1) at this stage. | | results | Results have been returned from the find service. You can modify the list of suggestions returned (parameter 1) and access the extended attributes object (parameter 2) including properties such as **ContainerCount**. | | noresults | No matching results were returned from the find service. | | display | The suggestions have been shown to the user. | | select | The user has selected a suggestion. The chosen suggestion can be accessed (parameter 1). | | prepopulate | The full address has been returned from the retrieve service. The address object (parameter 1) can be accessed and modified before fields are populated, as well as full list of language variations (parameter 2) for the address. | | populate | The address fields have been populated. This is the most common event to listen for, and will allow you to populate your own fields with your own logic using the address object (parameter 1) and the list of address variations (parameter 2). | | country | The country has been changed. The selected country object (parameter 1) with **iso2**, **iso3** and **name** properties is passed through. | | manual | When the **manualEntry** option is passed through and the user selects the option to enter their address manually this event will fire. | | error | An error has occured. The error message (parameter 1) is passed through. Typically errors are not shown to the user, but can be handled manually here if needed. | ## Dynamic pages When the control loads it will need to be able to find your address fields in order to bind to the page events and listen for the user typing into the field. This becomes more tricky when working with dynamic pages and asynchronous postbacks. If the control is not loading at the correct time when your address form is rendered onto the page, you can call the **load** method on the control manually. If you are loading dynamic HTML, you can include a call to reload your previously defined control object, or include your full initialisation script as part of the HTML being rendered. ```html theme={null}

Shopify Plus

Adobe Commerce

BigCommerce

Microsoft Dynamics 365

Salesforce Commerce Cloud

commercetools

Salesforce CRM

Shopware

Reapit

Oracle Cloud

Works with:

Supported Loqate Services:

Works with:

Supported Loqate Services: