WooCommerce Plugin

Overview

The SnapAddress WooCommerce plugin adds UK postcode lookup to WooCommerce's address forms. Someone types a postcode, picks their address from a dropdown, and the address fields fill in.

It works on three screens:

• Checkout: classic checkout and Checkout Blocks, billing and shipping. On as soon as you add your API key.
• My Account > Addresses: customers updating their saved billing and shipping addresses. Off until you turn it on.
• The admin order screen: staff taking phone and manual orders. Off until you turn it on.

This page describes version 1.2.1, the current release on the WordPress plugin directory.

Requirements: WooCommerce 8.0+, WordPress 6.0+, and PHP 7.4+. WooCommerce must be installed and active. Tested up to WordPress 7.1 and WooCommerce 11.1. The plugin declares compatibility with WooCommerce's High-Performance Order Storage (HPOS) and Checkout Blocks.

Installation

The plugin is free on the WordPress plugin directory.

From your WordPress admin

1. Go to Plugins > Add New and search for SnapAddress
2. Click Install Now, then Activate

Manual upload

1. Download the plugin ZIP
2. Go to Plugins > Add New > Upload Plugin
3. Choose the ZIP file and click Install Now
4. Click Activate

Configuration

1. Go to WooCommerce → SnapAddress
2. Tick Enable UK address autocomplete (on by default)
3. Enter your API key (get one from the dashboard)
4. Under Show the lookup on, tick the screens you want. Checkout is ticked by default
5. Click Save changes, then Test connection to confirm the key and see your remaining credits

With the defaults, that's all you need to do. The lookup appears on your checkout automatically.

Settings reference

Upgrading from 1.1 changes nothing until you tick a new screen: checkout keeps working exactly as before.

A Test connection button on the settings page checks the key in the field and shows your remaining credits and when your earliest credits expire. At a zero balance it also warns that the lookup has fallen back to manual address entry.

If WooCommerce's own address autocomplete is also switched on (WooCommerce → Settings → General → Address autocomplete, WooCommerce 10.4 and later), the settings page shows a warning. Both would attach to the same address field, so use one or the other.

The plugin doesn't show low-balance notices elsewhere in WordPress admin. SnapAddress emails your account address when your balance runs low, and again when it runs out.

Your API key is stored in your WordPress database as a plugin setting, so anyone with access to the settings page can see it. Use a dedicated key per store, and revoke it from the dashboard if it's ever exposed.

How it works

At checkout, the lookup is search-first: instead of adding an extra field to an already long form, the search field stands in for the address fields. It appears directly above where the street address would be, and the individual address fields stay hidden until the customer has picked their address.

1. The customer types a postcode or address (minimum 2 characters) in the lookup field
2. The plugin calls the SnapAddress API through a nonce-protected WordPress REST route, so your API key stays on the server and is never exposed in the page
3. Matching suggestions appear in a dropdown; a postcode with more than one address shows how many it holds. Choosing one loads the addresses at that postcode; if there's only one, it's filled in straight away
4. The customer selects their address — the address fields appear, filled in. They can also click Enter address manually at any point to skip the lookup

The suggestions the field shows as the customer types are free. One credit is spent when the customer chooses a suggestion and its list of addresses loads; picking an address from that list costs nothing more. So a completed search normally costs one lookup. A customer who opens a second suggestion spends a second. Budget one lookup per address captured. See how we size packs for a worked example.

The list shows up to 100 addresses for a postcode, which covers every standard postcode.

Fields it fills

The Company field isn't filled. When the chosen address has no second line or county, any value already in those fields is cleared, so a replaced address never keeps part of the old one. On classic checkout, in My Account and on the admin order screen, the cursor then moves to the first address line so it can be checked.

A few behaviours worth knowing about:

• UK only, by design. The lookup appears when the selected country is United Kingdom. For any other country the standard WooCommerce address fields show as normal. WooCommerce lists Jersey, Guernsey and the Isle of Man as separate countries, so they don't get the lookup.
• Returning customers keep their saved address. If a customer already has an address filled in (a first address line, or a town and postcode), the fields show immediately, pre-filled — no extra clicks to check out. The search field stays available above the street address in case they want to look up a different address.
• Nothing ever blocks. If the lookup can't run — no credits, an invalid or revoked key, network trouble, or a cached page — the plugin shows a short note that the lookup is unavailable and reveals the standard address fields, so customers can always complete their order. This applies on every screen the lookup appears on. The lookup returns when the page is reloaded.

Where the lookup appears

Checkout

Classic checkout and Checkout Blocks, on both the billing and shipping forms. No configuration is needed beyond your API key.

On Checkout Blocks, picking a shipping address also fills the billing address only when Use same address for billing is ticked, matching WooCommerce's own behaviour. (Before 1.2.0 it filled billing either way.)

My Account > Addresses

Tick My Account > Addresses to add the lookup where logged-in customers edit their saved addresses (My Account → Addresses → Edit). It behaves as it does at checkout:

• A customer with a saved address sees it filled in, with the search field above it for looking up a different one.
• A customer with no saved address sees the search field in place of the address fields. WooCommerce doesn't pre-select a country on this form, so the lookup appears once they choose United Kingdom.
• If saving fails — a required field left empty, say — the page reloads with WooCommerce's error messages and the address fields visible, so the errors point at something the customer can see.

It also covers the Change address link on a WooCommerce Subscriptions subscription, which opens the same form.

The admin order screen

Tick Admin order and subscription screens to add the lookup to the order screen, for staff taking orders by phone or entering them by hand. It works on new and existing orders, with either order storage (HPOS or the legacy posts table), and on WooCommerce Subscriptions subscriptions.

1. Open an order (or WooCommerce → Orders → Add order)
2. Click the pencil next to Billing or Shipping
3. With United Kingdom selected, a Find a UK address field appears above Address line 1. Search, pick the address, and the fields fill in

The admin version is built for staff rather than customers:

• Nothing is hidden. Every field stays visible, and there's no "Enter address manually" link.
• The field stays after you pick an address, cleared and ready to search again.
• It works alongside WooCommerce's own tools. Load billing address, Copy billing address and choosing a customer all work as normal, and there's only ever one search field per address.

Staff need permission to edit orders. A lookup made by staff uses a credit exactly like one made by a customer.

Not covered

• The cart's shipping calculator. It has no street address field — only country, county, town and postcode — so a lookup would add nothing.
• Registration. WooCommerce's registration form has no address fields.
• A user's profile page in wp-admin (the customer billing and shipping fields on Users → Edit). Not yet supported.

Customisation

Positioning the lookup field

By default the lookup renders directly above the street address field. To place it anywhere else, add an empty element with a data-snapaddress-anchor attribute to your template and the lookup renders inside it:

<div data-snapaddress-anchor="billing"></div>

Use "billing" or "shipping" to position each section's lookup independently. Two things to note:

• Place the anchor outside the billing/shipping fields container — WooCommerce re-orders the elements inside it, which would move your anchor
• If more than one anchor exists for a section, the first one on the page wins

Requires plugin version 1.1.0 or later. Works on the classic checkout, Checkout Blocks and My Account. The admin order screen ignores anchors.

CSS styling

On classic checkout and in My Account, the search field inherits your theme's own field styling, so in most themes it already matches the fields around it. The plugin renders BEM-style classes you can target for custom styling:

/* The lookup wrapper */
.snapaddress-lookup { }
 
/* The lookup wrapper when the address fields are already visible
   (e.g. a returning customer with a saved address) */
.snapaddress-lookup--prefilled { }
 
/* The search field and its label */
.snapaddress-lookup__input { }
.snapaddress-lookup__label { }
 
/* The suggestions dropdown */
.snapaddress-dropdown { }
 
/* A single suggestion row, and the highlighted row */
.snapaddress-suggestion { }
.snapaddress-suggestion--active { }
 
/* "Searching…", "No addresses found", and the fallback note */
.snapaddress-loading { }
.snapaddress-empty { }
.snapaddress-notice { }
 
/* The "enter address manually" link */
.snapaddress-lookup__manual { }

The dropdown's colours, spacing and size are set with --snapaddress-* custom properties (for example --snapaddress-dropdown-bg and --snapaddress-item-color), listed at the top of the plugin's stylesheet. Override them to restyle it. The dropdown switches to dark colours when the visitor's device is in dark mode; if your store stays light, override the custom properties inside @media (prefers-color-scheme: dark) too. None of the plugin's own rules use !important.

On the admin order screen, the field uses WooCommerce's own admin field styling and a small stylesheet of its own (the wrapper also has .snapaddress-lookup--admin). The --snapaddress-* custom properties don't apply there.

Hooks and filters

The plugin doesn't currently expose PHP filters or actions — control the position with the data-snapaddress-anchor attribute and the appearance with the CSS classes above.

Translations

Every customer-facing string can be translated. The text domain is snapaddress, and a snapaddress.pot template ships in the plugin's languages folder.

Privacy

When a customer — or a member of staff on the admin order screen — uses the lookup, your server sends SnapAddress the text they type (a postcode or partial address) and the postcode of the suggestion they choose. The request comes from your WordPress server, not the browser, so no customer IP address, name, email or payment detail is sent. The plugin sets no cookies. See our privacy policy for what we process and how long we keep it.

Troubleshooting

The address lookup field does not appear

• Confirm the plugin is activated in Plugins > Installed Plugins
• Check that Enable UK address autocomplete is ticked and an API key is set in WooCommerce → SnapAddress
• Check the screen is ticked under Show the lookup on — My Account and the admin order screen are off until you tick them
• Check the selected country — the lookup only appears when the country is United Kingdom. In My Account, a customer with no saved address needs to choose it first
• On the admin order screen, click the pencil next to Billing or Shipping — the field sits inside that edit panel. The user also needs permission to edit orders
• If using a custom theme, ensure the WooCommerce templates aren't overridden in a way that removes the address fields

Customers see two address lookups

WooCommerce's own address autocomplete is also switched on, and the SnapAddress settings page shows a warning when it is. Turn off Address autocomplete in WooCommerce → Settings → General, or untick the screen in SnapAddress — use one or the other.

The address fields are hidden at checkout

This is the search-first design: for new customers the fields stay hidden until an address is selected, keeping the form short. They appear as soon as the customer picks an address, clicks Enter address manually, or — for customers with an address already filled in — immediately on page load, pre-filled. If the lookup service is ever unavailable, the fields are revealed automatically so checkout is never blocked. Fields are never hidden on the admin order screen.

Customers see "Address lookup is unavailable right now"

The lookup couldn't run, so the plugin fell back to manual entry. Customers never see the underlying error. Check, in this order:

• Your key: click Test connection in WooCommerce → SnapAddress. If it fails, the key is wrong or has been revoked — generate a new one from the dashboard and save it.
• Your credits: Test connection shows your balance. At zero, add a credit pack from the pricing page.
• Page caching: the lookup uses a WordPress security token (a nonce) that expires. If a caching plugin or your host caches the checkout or My Account pages, the token goes stale and every lookup fails. Exclude them from page caching. On the admin order screen, an order left open for about a day can hit the same expiry — reload the page.
• The logs: with WP_DEBUG enabled, the plugin writes diagnostic lines starting SnapAddress: to your PHP error log. A line can include the postcode being looked up, but never your API key or the addresses returned. Out of credits means your balance is zero; before 1.2.1 the plugin logged this as Rate limited instead.

"No addresses found" for a postcode

The postcode isn't in Royal Mail's PAF yet — for example, a new development that hasn't been added. Customers can still click Enter address manually. You can check a postcode directly with the API.

Uninstalling

Deactivate and delete the plugin from Plugins > Installed Plugins. Deactivating keeps your settings. Deleting removes them — the API key, the enable setting, your choice of screens and the cached credit balance — and the plugin stores nothing else in your WordPress database. On a multisite network, deletion cleans up the current site's settings only.