# Installing Address Validation & Postcode Lookup for ShopWired

This guide walks you through installing and configuring the Ideal Postcodes address validation integration for ShopWired. The integration enables address finder or postcode lookup at checkout, account address forms, and admin pages.

## Overview[​](#overview "Direct link to Overview")

**What this integration provides:**

* Real-time UK address validation and postcode lookup
* Enhanced checkout experience with faster address entry
* Reduced delivery errors and customer support tickets
* Improved data quality across all address collection points

**Choose Your Method:** Use the integration for Address Finder or UK Postcode Lookup to enhance your ShopWired checkout experience. If unsure which method is best, read our [Address Finder vs Postcode Lookup comparison guide](https://ideal-postcodes.co.uk/guides/postcode-lookup-vs-address-finder).

## Where Address Lookup is Applied[​](#where-address-lookup-is-applied "Direct link to Where Address Lookup is Applied")

The integration adds address validation or postcode lookup to:

* **Checkout Billing Form** - Customer billing address entry
* **Checkout Shipping Form** - Customer shipping address entry
* **Account Address Forms** - Customer address book management
* **Admin Dashboard** - Via [Browser Extension](/docs/integrations/browser-extension.md) (optional)

***

## Screenshots[​](#screenshots "Direct link to Screenshots")

### Address Finder[​](#address-finder "Direct link to Address Finder")

![Activate Address Finder on your address collection forms-screenshot](https://img.ideal-postcodes.co.uk/shopwired-autocomplete.png)

### Postcode Lookup[​](#postcode-lookup "Direct link to Postcode Lookup")

![Enable Postcode Lookup on your checkout pages-screenshot](https://img.ideal-postcodes.co.uk/shopwired-postcode-lookup.png)

***

## 1. Sign up for a Free Trial and Get Your API Key[​](#1-sign-up-for-a-free-trial-and-get-your-api-key "Direct link to 1. Sign up for a Free Trial and Get Your API Key")

Before installing the integration, you'll need an Ideal Postcodes API Key.

**Steps:**

1. Sign up for a free account at [ideal-postcodes.co.uk/sign-up](https://account.ideal-postcodes.co.uk/users/sign_up)
2. Navigate to the **KEYS** section in your account
3. Copy your API Key - you'll need this to complete the setup in ShopWired. It's a string of characters that begins with the letters `ak_`

💡 **All new accounts include 50 free test credits - no payment required.**

***

## 2. Install the ShopWired Integration[​](#2-install-the-shopwired-integration "Direct link to 2. Install the ShopWired Integration")

You can install address validation on different pages of your ShopWired site. Choose the installation method(s) based on where you want address validation to appear.

### Prepare Your Script[​](#prepare-your-script "Direct link to Prepare Your Script")

Both installation methods use a similar script with your API Key. You'll customize this based on your needs.

### Method A: Checkout Page (Recommended)[​](#method-a-checkout-page-recommended "Direct link to Method A: Checkout Page (Recommended)")

**Best for:** Checkout billing and shipping address validation.

**Steps:**

1. From your ShopWired Admin, go to **Checkout** → **Design and Display**

2. Scroll down to **Advanced Customisation** and click the **JS** tab

   ![Insert configuration code-screenshot](/assets/images/shopwired-checkout-879f981ef5b08ba2ae0afe780233fa5d.png)

3. In the **Script contents** editor, paste the following code:

```
<script>

	window.idpcConfig = {

		apiKey: "ak_xxxxxxxxxx", // Replace with your actual API Key

		autocompleteOverride: {

			populateCounty: false,

			populateOrganisation: false,

		},

		postcodeLookupOverride: {

			populateCounty: false,

			populateOrganisation: false,

		},

	};

</script>



<script

	async

	type="text/javascript"

	crossorigin="anonymous"

	src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/shopwired@3.0.2/dist/shopwired.min.js"

></script>
```

4. Replace `ak_xxxxxxxxxx` with your actual API Key from Step 1
5. Click **Save**

### Method B: Account Pages (Optional)[​](#method-b-account-pages-optional "Direct link to Method B: Account Pages (Optional)")

**Best for:** Account registration and address book pages.

**When to use:** If you want address validation beyond checkout forms.

**Steps:**

1. From your ShopWired Admin, go to **Website** → **Themes**

2. Click **Code Editor**

   ![Go to theme template-screenshot](/assets/images/shopwired-code-editor-bf0ffc698b9a07cfd83b68f133fa91b7.png)

3. Navigate to **Views** → **Templates** → **master.twig**

4. Scroll to the bottom of the editor, just before the `</body>` tag

5. Paste the following code:

```
<script>

	window.idpcConfig = {

		apiKey: "ak_xxxxxxxxxx", // Replace with your actual API Key



		// Enable/disable lookup methods

		postcodeLookup: true, // Enable Postcode Lookup

		autocomplete: true, // Enable Address Finder



		autocompleteOverride: {

			populateCounty: false,

			populateOrganisation: true,

		},

		postcodeLookupOverride: {

			populateCounty: false,

			populateOrganisation: true,

		},

	};

</script>



<script

	async

	type="text/javascript"

	crossorigin="anonymous"

	src="https://cdn.jsdelivr.net/npm/@ideal-postcodes/shopwired@3.0.2/dist/shopwired.min.js"

></script>
```

![Insert configuration code-screenshot](/assets/images/shopwired-master-twig-2865a666fa7f478f53901cf9e0c1ea7d.png)

6. Replace `ak_xxxxxxxxxx` with your actual API Key from Step 1
7. Click **Save**

***

## 3. Configure Address Lookup Options (Optional)[​](#3-configure-address-lookup-options-optional "Direct link to 3. Configure Address Lookup Options (Optional)")

By default, both Address Finder and Postcode Lookup are enabled. You can customize the behavior by modifying the configuration in your script.

### Default Configuration[​](#default-configuration "Direct link to Default Configuration")

The available configuration options are:

```
window.idpcConfig = {

	apiKey: "ak_xxxxxxxxxx", // Your API Key (required)



	// Enable/disable lookup methods

	postcodeLookup: true, // Enable Postcode Lookup

	autocomplete: true, // Enable Address Finder (autocomplete)



	// Advanced configuration (optional)

	autocompleteOverride: {

		populateOrganisation: true, // Auto-fill company name from address

		populateCounty: false, // Auto-fill county field (not recommended for UK)

	},

	postcodeLookupOverride: {

		populateOrganisation: true, // Auto-fill company name from address

		populateCounty: false, // Auto-fill county field (not recommended for UK)

	},

};
```

### Configuration Options[​](#configuration-options "Direct link to Configuration Options")

| Setting                  | Type    | Default | Description                                        |
| ------------------------ | ------- | ------- | -------------------------------------------------- |
| **apiKey**               | String  | ""      | Your Ideal Postcodes API Key (required)            |
| **postcodeLookup**       | Boolean | true    | Enable traditional postcode lookup                 |
| **autocomplete**         | Boolean | true    | Enable Address Finder (type-ahead search)          |
| **populateOrganisation** | Boolean | true    | Auto-fill company name field from selected address |
| **populateCounty**       | Boolean | false   | Auto-fill county field (not recommended for UK)    |

💡 **Tip:** Set `postcodeLookup: false` to use only Address Finder, or set `autocomplete: false` to use only Postcode Lookup.

***

## 4. Test the Integration[​](#4-test-the-integration "Direct link to 4. Test the Integration")

To verify the address validation is working:

1. Go to your ShopWired checkout page
2. Begin typing an address in the billing or shipping address field
3. The Ideal Postcodes address lookup tool should automatically suggest addresses as you type

***

## 5. Advanced: Supported Forms and Field Selectors[​](#5-advanced-supported-forms-and-field-selectors "Direct link to 5. Advanced: Supported Forms and Field Selectors")

**When needed:** For custom implementations or troubleshooting.

The integration automatically detects and binds to ShopWired address forms using these CSS selectors:

### Billing Form[​](#billing-form "Direct link to Billing Form")

```
{

	"line_1": "[name=\"billing_address1\"]",

	"line_2": "[name=\"billing_address2\"]",

	"line_3": "[name=\"billing_address3\"]",

	"post_town": "[name=\"billing_city\"]",

	"postcode": "[name=\"billing_postcode\"]",

	"country": "[name=\"billing_country_id\"]"

}
```

### Shipping Form[​](#shipping-form "Direct link to Shipping Form")

```
{

	"line_1": "[name=\"shipping_address1\"]",

	"line_2": "[name=\"shipping_address2\"]",

	"line_3": "[name=\"shipping_address3\"]",

	"post_town": "[name=\"shipping_city\"]",

	"postcode": "[name=\"shipping_postcode\"]",

	"country": "[name=\"shipping_country_id\"]"

}
```

### Customer Form[​](#customer-form "Direct link to Customer Form")

```
{

	"line_1": "[name=\"address_line1\"]",

	"line_2": "[name=\"address_line2\"]",

	"line_3": "[name=\"address_line3\"]",

	"post_town": "[name=\"city\"]",

	"postcode": "[name=\"postcode\"]",

	"country": "[name=\"country_id\"]"

}
```

### Billing Edit Form[​](#billing-edit-form "Direct link to Billing Edit Form")

```
{

	"line_1": "[name=\"billing_address_line1\"]",

	"line_2": "[name=\"billing_address_line2\"]",

	"line_3": "[name=\"billing_address_line3\"]",

	"post_town": "[name=\"billing_city\"]",

	"postcode": "[name=\"billing_postcode\"]",

	"country": "[name=\"billing_country_id\"]"

}
```

### Shipping Edit Form[​](#shipping-edit-form "Direct link to Shipping Edit Form")

```
{

	"line_1": "[name=\"shipping_address_line1\"]",

	"line_2": "[name=\"shipping_address_line2\"]",

	"line_3": "[name=\"shipping_address_line3\"]",

	"post_town": "[name=\"shipping_city\"]",

	"postcode": "[name=\"shipping_postcode\"]",

	"country": "[name=\"shipping_country_id\"]"

}
```

***

## 6. Version Management[​](#6-version-management "Direct link to 6. Version Management")

### Automatic Updates[​](#automatic-updates "Direct link to Automatic Updates")

The integration automatically updates to the latest version using the version suffix in the script URL. This ensures you always have the latest features and bug fixes.

### Version Pinning (Optional)[​](#version-pinning-optional "Direct link to Version Pinning (Optional)")

**When to use:** If you need to lock to a specific version for stability.

The current version in the examples is `@3.0.2`. You can pin to a specific version by keeping this exact version number, or update it to a newer version as they become available.

All versions are tracked in our [Changelog](https://github.com/ideal-postcodes/shopwired/releases).

***

## 7. Admin Dashboard Integration (Optional)[​](#7-admin-dashboard-integration-optional "Direct link to 7. Admin Dashboard Integration (Optional)")

![Browser Extension-screenshot](https://img.ideal-postcodes.co.uk/shopwired-extension-demo.gif)

**When needed:** If you want address validation in your ShopWired admin panel.

To enable address validation on admin pages, install our [Browser Extension](https://ideal-postcodes.co.uk/browser-extension). This adds address lookup functionality to order management and customer address forms in your admin dashboard.

***

## 8. Troubleshooting[​](#8-troubleshooting "Direct link to 8. Troubleshooting")

| Issue                                   | Solution                                                                                                                                                                                 |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No address suggestions appear           | • Verify API Key is correct in your script<br />• Check key balance in your account dashboard<br />• Ensure country is set to UK territory<br />• Check browser console (F12) for errors |
| Script not loading                      | • Verify script is saved in Advanced Customisation or master.twig<br />• Clear browser cache and test in incognito mode<br />• Check for JavaScript errors in console                    |
| Works on checkout but not account pages | • Install via Method B (master.twig) for account page support<br />• Verify script is placed before `</body>` tag                                                                        |
| Address fields not populating           | • Check that field selectors match your theme<br />• Verify custom theme hasn't changed default field names<br />• Review browser console for JavaScript errors                          |

info

Need help? Contact our support team via live chat on our website or email <support@ideal-postcodes.co.uk>.