=== SnapAddress ===
Contributors: clearpathlabs
Tags: address autocomplete, postcode lookup, uk addresses, woocommerce checkout, royal mail paf
Requires at least: 6.0
Tested up to: 7.1
Stable tag: 1.2.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

UK address autocomplete for WooCommerce checkout, My Account and admin orders. Powered by Royal Mail PAF data, not Google.

== Description ==

SnapAddress adds fast, accurate UK address autocomplete to WooCommerce. As someone types a postcode, they see a dropdown of matching addresses and can select theirs in one click.

It works wherever a full UK address gets typed:

* **Checkout** - classic and block-based
* **My Account > Addresses** - customers updating their saved billing and shipping addresses (including the WooCommerce Subscriptions "Change address" flow)
* **Admin order screen** - staff taking phone and manual orders, on new and existing orders and on WooCommerce Subscriptions subscriptions

Checkout is on as soon as you add your API key. My Account and the admin order screen are opt-in: tick them in WooCommerce > SnapAddress.

**Built on Royal Mail PAF data, not Google.** Unlike Google Places-based plugins, SnapAddress uses the Royal Mail Postcode Address File - the UK's most accurate and up-to-date address database with more than 30 million addresses. This means:

* **Flat-level accuracy** - flats, apartments and units that Royal Mail delivers to individually are returned in full
* **Monthly updates** from Royal Mail
* **No Google Maps API key required** - simpler setup, no unpredictable Google billing

**Works with WooCommerce Checkout Blocks.** SnapAddress registers as a WooCommerce Blocks checkout integration and supports both the block-based checkout (default since WooCommerce 8.3) and classic checkout. The search box sits directly above the street address field, matches your theme's field styling, and falls back to normal manual entry if the lookup is ever unavailable.

**Key features:**

* UK postcode lookup and address autocomplete
* Works with Checkout Blocks and classic checkout
* Faster phone and manual orders: address lookup on the admin order screen
* Address lookup in My Account for customers updating saved addresses
* Choose which screens show the lookup
* HPOS (High-Performance Order Storage) compatible
* No Google Maps API key needed
* Free trial included - 100 lookups, no credit card required
* Transparent, published pricing - no sales calls
* Pay-as-you-go credit packs, no monthly subscription
* Install in under 2 minutes

**Getting started:**

1. Install and activate the plugin
2. Sign up for a free API key at [snapaddress.io](https://www.snapaddress.io)
3. Enter your API key in WooCommerce > SnapAddress
4. Your checkout now has UK address autocomplete
5. Optionally, tick My Account and the admin order screen on the same settings page

**Pricing:**

SnapAddress uses transparent, published pricing with no sales calls. You buy a one-time pack of lookup credits and top up whenever you like - there is no monthly subscription.

* **Free trial** - 100 lookups, no credit card required
* **Starter** - 500 lookups for GBP 17.50
* **Standard** - 2,000 lookups for GBP 60
* **Business** - 5,000 lookups for GBP 140
* **Pro** - 15,000 lookups for GBP 375

Purchased credits are valid for 12 months (trial credits for 3 months), in line with Royal Mail PAF licensing terms. Visit [snapaddress.io/pricing](https://www.snapaddress.io/pricing) for full details.

**Third-party service disclosure:**

This plugin connects to the SnapAddress API at `api.snapaddress.io` to provide address autocomplete functionality. When a customer (at checkout or in My Account) or a member of staff (on the admin order screen) types a postcode or partial address into the lookup, the plugin sends that search text to the SnapAddress API and receives matching address suggestions.

* Service URL: [https://api.snapaddress.io](https://api.snapaddress.io)
* Terms of service: [https://www.snapaddress.io/terms](https://www.snapaddress.io/terms)
* Privacy policy: [https://www.snapaddress.io/privacy](https://www.snapaddress.io/privacy)

**About SnapAddress:**

SnapAddress is built by [Clearpath Labs Ltd](https://clearpathlabs.co.uk), a UK-based software company and licensed Royal Mail PAF Solutions Provider. Powered by Royal Mail PAF.

== Installation ==

1. Upload the `snapaddress` folder to `/wp-content/plugins/` or install directly from the WordPress plugin directory
2. Activate the plugin through the 'Plugins' menu
3. Go to WooCommerce > SnapAddress
4. Enter your API key (get a free one at [snapaddress.io](https://www.snapaddress.io))
5. Click "Test connection" to verify
6. Address autocomplete is now active on your checkout
7. To add it to My Account > Addresses or the admin order screen, tick them under "Show the lookup on" and save

== Frequently Asked Questions ==

= Do I need a Google Maps API key? =

No. SnapAddress uses Royal Mail PAF data directly. There's no dependency on Google Maps, Google Places, or any Google service.

= Does it work with WooCommerce Checkout Blocks? =

Yes. SnapAddress works with both the block-based checkout and classic checkout, on both the shipping and billing address forms.

= Is there a free trial? =

Yes. New accounts get 100 free lookups with no credit card required - enough to test the integration on your checkout before buying a credit pack.

= How does pricing work? =

You buy a one-time pack of lookup credits (from 500 upwards). The suggestions shown while someone types are free; a credit is used only when they pick a postcode and the full list of addresses is fetched - so a typical address search costs one credit. There is no monthly subscription. When your credits run low, you top up with another pack whenever you choose.

= What happens when my credits run out? =

Everything keeps working. Wherever the lookup appears - checkout, My Account or the admin order screen - it falls back to standard manual address entry, so customers can still complete their orders and staff can still type an address. You top up when you're ready.

= How do I turn on lookup in My Account or the admin order screen? =

Go to WooCommerce > SnapAddress and tick "My Account > Addresses" and/or "Admin order and subscription screens" under "Show the lookup on", then save. Both are off until you turn them on. Checkout can be switched off on the same screen.

= Do staff lookups in wp-admin use credits? =

Yes. A lookup made by a member of staff on the admin order screen uses a credit exactly like one made by a customer at checkout. The suggestions shown while typing are free; a credit is used when a postcode is picked and its addresses are fetched.

= Do credits expire? =

Purchased credits are valid for 12 months from the date of purchase, and free trial credits for 3 months. This is a requirement of Royal Mail's PAF licensing terms, which apply to all PAF-based address providers. A 500-credit Starter pack lasts most small stores several months.

= How accurate is the address data? =

SnapAddress uses Royal Mail's Postcode Address File (PAF), which contains more than 30 million UK addresses and is updated monthly. It includes flat-level accuracy for multi-occupancy buildings, which Google Places does not provide for UK addresses.

= What customer data does the plugin process? =

When a customer or member of staff uses the address lookup, the search text they type (a postcode or partial address) is sent to the SnapAddress API to return matching suggestions. No names, emails, or payment details are sent. See our privacy policy at [snapaddress.io/privacy](https://www.snapaddress.io/privacy) for full details of what is processed and retained.

= Can I use it on multiple WooCommerce stores? =

Yes. You can create multiple API keys from your SnapAddress dashboard, and usage is tracked per key.

= Can I control where the search box appears? =

By default the search box appears directly above the street address field. On checkout and in My Account, if your theme uses a custom layout and you want it somewhere else, add an empty element with a `data-snapaddress-anchor` attribute where the search box should render, for example `<div data-snapaddress-anchor="billing"></div>` (use `"shipping"` for the shipping section). The search box renders inside that element. Place the anchor outside the billing/shipping fields container (WooCommerce re-orders elements inside it), and if more than one anchor exists for a section, the first one on the page wins.

= Can I restyle the search box to match my theme? =

Yes. On classic checkout the search box deliberately inherits your theme's own checkout field styling, so in most themes it already matches the fields around it without any work. To customise it further, target `.snapaddress-lookup__input` for the field and `.snapaddress-lookup__label` for its label, or override the `--snapaddress-*` custom properties listed at the top of the plugin's stylesheet to restyle the suggestions dropdown. None of the search box's own styling uses `!important`, so plain rules in Appearance > Customise > Additional CSS will apply. On the admin order screen the search box uses WooCommerce's own admin field styling, so it matches the other order fields.

== Screenshots ==

1. Address autocomplete dropdown in the WooCommerce checkout
2. Plugin settings page in wp-admin, including the screens the lookup appears on
3. Address selection populating checkout fields
4. Address lookup on the admin order screen, for phone and manual orders

== Changelog ==

= 1.2.0 =
* Added: address lookup in My Account > Addresses, for customers updating their saved billing and shipping addresses (also covers the WooCommerce Subscriptions "Change address" flow). Off by default - enable it in WooCommerce > SnapAddress
* Added: address lookup on the admin order screen (new and existing orders, HPOS and legacy order storage, and WooCommerce Subscriptions subscriptions), for staff taking phone and manual orders. Off by default - enable it in WooCommerce > SnapAddress. Staff lookups use credits like any other
* Added: choose which screens show the lookup. Checkout stays on as before and can now be switched off independently
* Added: a warning on the settings page when WooCommerce's own address autocomplete is also switched on, so customers don't see two lookups
* Fixed: on classic checkout, replacing a saved address with the lookup now clears parts the new address doesn't have (such as a second address line or county) instead of keeping the old ones
* Fixed: on the block-based checkout, choosing a shipping address no longer overwrites a different billing address when "Use same address for billing" is unticked
* Improved: the lookup no longer loads on the order-received and order-pay pages, which have no address fields

= 1.1.1 =
* Fixed: on classic checkout, themes that set a fixed height or padding on text inputs no longer cause the "Select your address" label to overlap the search box
* Improved: the classic search box now inherits your theme's checkout field styling, so it matches the fields around it (this may change its appearance slightly on upgrade)

= 1.1.0 =
* Improved: the lookup widget now appears directly above the street address field, fixing placement on checkouts with customised field layouts
* Fixed: logged-in customers with a saved address now see their address immediately; the lookup stays available above it to search for a different address
* Fixed: address fields entered before a checkout validation error now stay visible after the page reloads
* Added: theme developers can position the widget anywhere by adding an element with data-snapaddress-anchor="billing" (or "shipping") - the widget renders inside it

= 1.0.0 =
* Initial release
* UK postcode lookup and address autocomplete
* WooCommerce Checkout Blocks support
* Classic checkout support
* HPOS compatibility
* Settings page with API key configuration and connection test

== Upgrade Notice ==

= 1.2.0 =
New: address lookup for My Account and the admin order screen - off until you enable it in WooCommerce > SnapAddress (staff lookups use credits). Checkout is unchanged. Also fixes a block checkout billing-address bug.

= 1.1.0 =
Better widget placement on customised checkouts, and saved customer addresses now show immediately.

= 1.0.0 =
Initial release of SnapAddress for WooCommerce.