# Installing Address Validation & Postcode Lookup for BigCommerce
This guide walks you through installing and configuring the Ideal Postcodes address validation integration for BigCommerce. 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 BigCommerce 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) or [watch the video](https://www.youtube.com/watch?v=2l6armAn25k).
## 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 Registration** - New customer account creation
* **Account Management** - 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")
### Postcode Lookup[](#postcode-lookup "Direct link to Postcode Lookup")
***
## 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 BigCommerce. 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 BigCommerce Integration[](#2-install-the-bigcommerce-integration "Direct link to 2. Install the BigCommerce Integration")
**Installation Overview:**
We recommend installing via both **Script Manager** and **Site Verification Tags** for complete coverage:
* **Script Manager** - Official method for checkout customization (required for checkout address validation)
* **Site Verification Tags** - Enables address validation on account registration and address book pages
### Prepare Your Script[](#prepare-your-script "Direct link to Prepare Your Script")
Both installation methods use the same script with your API Key. You'll need this script ready:
**Script Template:**
```
```
**Important:** Replace `ak_xxxxxxxxxx` with your actual API Key from Step 1.
### Method A: Install via Script Manager (Required for Checkout)[](#method-a-install-via-script-manager-required-for-checkout "Direct link to Method A: Install via Script Manager (Required for Checkout)")
**Best for:** Checkout address validation (billing and shipping forms).
**Steps:**
1. From your BigCommerce Admin, go to **Storefront** → **Script Manager**
2. Click the blue **Create a Script** button
3. Configure the script with these settings:
* **Name:** Ideal Postcodes Address Validation
* **Location on page:** Footer
* **Pages:** Checkout
* **Script category:** Essential
* **Script type:** Script
4. In the **Script contents** editor, paste your prepared script (with your API Key)
5. Click **Save**
### Method B: Install via Site Verification Tags (Optional)[](#method-b-install-via-site-verification-tags-optional "Direct link to Method B: Install via Site Verification Tags (Optional)")
**Best for:** Account registration and address book pages.
**When to use:** If you want address validation beyond checkout forms.
**Steps:**
1. From your BigCommerce Admin, go to **Advanced Settings** → **Tracking Code**
2. In the **Analytics** page under **General Settings**, check the **Site Verification Tags** checkbox
3. Switch to the **Site Verification Tags** tab
4. Paste your prepared script (with your API Key) into the text area
5. 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 integration comes with these default settings:
```
window.idpcConfig = {
apiKey: "ak_xxxxxxxxxx", // Your API Key (required)
// Enable/disable lookup methods
postcodeLookup: true, // Enable Postcode Lookup
autocomplete: true, // Enable Address Finder (autocomplete)
// Field population options
populateOrganisation: true, // Auto-fill company name from address
populateCounty: false, // Auto-fill county field (not recommended for UK)
// Advanced configuration (optional)
autocompleteOverride: {}, // Override Address Finder settings
postcodeLookupOverride: {}, // Override Postcode Lookup settings
};
```
### 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:** For more advanced configuration options, see our [integration configuration guide](https://ideal-postcodes.co.uk/guides/integration-configuration).
***
## 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 BigCommerce 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 BigCommerce address forms using these CSS selectors:
### Billing Address (Base)[](#billing-address-base "Direct link to Billing Address (Base)")
```
{
"line_1": "#FormField_8",
"line_2": "#FormField_9",
"post_town": "#FormField_10",
"postcode": "#FormField_13",
"country": "#FormField_11"
}
```
### Shipping Address[](#shipping-address "Direct link to Shipping Address")
```
{
"line_1": "#FormField_18",
"line_2": "#FormField_19",
"post_town": "#FormField_20",
"postcode": "#FormField_23",
"country": "#FormField_21"
}
```
### Customer Address Book[](#customer-address-book "Direct link to Customer Address Book")
```
{
"line_1": "#shipAddress1",
"line_2": "#shipAddress2",
"post_town": "#city",
"postcode": "#postCode",
"country": "#country"
}
```
***
## 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 `@3` 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.
To pin a specific version, replace `@3` with a specific version number in the script URL:
```
```
All versions are tracked in our [Changelog](https://github.com/ideal-postcodes/bigcommerce/releases).
***
## 7. Admin Dashboard Integration (Optional)[](#7-admin-dashboard-integration-optional "Direct link to 7. Admin Dashboard Integration (Optional)")
**When needed:** If you want address validation in your BigCommerce admin panel.
To enable address validation on admin pages, install our [Browser Extension](/docs/integrations/browser-extension.md). 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
• Check key balance in your account dashboard
• Ensure country is set to UK territory
• Check browser console (F12) for errors |
| Script not loading | • Verify script is saved in Script Manager or Site Verification Tags
• Check that script location is set to "Footer"
• Clear browser cache and test in incognito mode |
| Works on checkout but not account pages | • Install via Site Verification Tags (Method B) for account page support
• Verify Site Verification Tags checkbox is enabled |
| Address fields not populating | • Check that field selectors match your theme
• Verify custom theme hasn't changed default field IDs
• Review browser console for JavaScript errors |
info
Need help? Contact our support team via live chat on our website or email .