Mapbox Address Autocomplete for WooCommerce

WooCommerce checkout asks for a street, city, postcode, and country. It does not help the customer enter those values correctly. A missing house number, a postcode from another country, or a street name with a typo will usually still pass, because the fields are not empty.

Mapbox address autocomplete for WooCommerce changes that moment. As the customer types in address line 1, Mapbox Search Box returns real postal suggestions. Selecting one fills street, city, state, postcode, and country in a single step. Fewer keystrokes, fewer mismatches, fewer parcels that cannot be labelled.

This article explains what Mapbox Autofill does at checkout, how it differs from address validation, and how to connect it with Address Guard Pro. For the broader autocomplete flow, see the WooCommerce address autocomplete guide.

What Mapbox address autocomplete does at checkout

Mapbox Address Autofill is a search helper, not a carrier check. Required country, street, city, and postcode only prove the form is not empty. Mapbox helps the customer fill those fields from structured address data.

At checkout, Address Guard Pro attaches suggestions to address line 1. After a few characters, Mapbox Search Box returns matching streets and addresses. Choosing one fetches the full feature and populates the WooCommerce form:

• Address line 1 (street and house number)
• City
• State or region
• Postcode
• Country

The customer can still type freely. Autocomplete does not replace the form, and it does not force a selection. That is why it feels light at checkout: the correct, consistent address becomes the easy path.

Mapbox does not:

• Confirm that a carrier can deliver there (that is address validation)
• Block PO boxes or parcel lockers (that is a fulfilment rule)
• Replace shipping zones, tax, or carrier rates
• Replay a saved browser address (that is browser autofill)

Most stores that ship physical products need Mapbox for entry and a dedicated validation provider for deliverability. Autocomplete stops the typo. Validation checks the result before payment.

Why WooCommerce stores use Mapbox

Stores pick Mapbox when they already have a Mapbox token, want search-quality suggestions, or prefer not to put Google Places on checkout. Address Guard Pro uses a merchant-owned access token. The plugin does not bundle Mapbox usage, so you keep control of Mapbox billing.

What that buys you at checkout:

• Structured capture. Street, city, postcode, and country fill together instead of being typed as six separate guesses.
• Country-biased search. If the customer has already chosen a checkout country, suggestions stay in that market.
• Checkout Blocks and classic checkout. The same token powers both [woocommerce_checkout] and the current WooCommerce checkout.
• A token that stays on the server. Address Guard Pro calls Mapbox from WordPress. The access token is not exposed in checkout JavaScript.
• A clean split from validation. Mapbox handles search. Google Address Validation, Loqate Address Verify, or Smarty can still check deliverability.

That last point is the usual reason stores choose Mapbox over a single-vendor stack. Search quality and postal verification do not have to come from the same network.

The cost of skipping autocomplete is the usual chain: the customer types a street with no house number, fulfilment cannot buy a label, support emails the customer, and express orders miss the cutoff. Catching the mistake while they are still on checkout is cheaper than reconstructing the address after payment.

Mapbox Autofill vs address validation

Stores often treat “Mapbox at checkout” as a full address check. It is autocomplete. Address Guard Pro does not use Mapbox as a validation provider.

Product	Role at checkout	What the customer sees
Mapbox Address Autofill	Autocomplete	A suggestion dropdown on address line 1. Selecting one retrieves the feature and fills street, city, state, postcode, and country.
A validation provider (Google, Loqate, or Smarty)	Validation	A check before the order is placed. The store can warn, offer a corrected address, allow checkout, or block it.

Autofill helps the customer enter a complete address. Validation checks whether that address is real. If you only turn on Mapbox, a customer can ignore the dropdown and type a fake street. If you only turn on validation, more addresses fail because they were typed poorly in the first place.

The comparison of validation vs autocomplete is worth reading if you are still deciding which layer to enable first.

Most stores that print shipping labels need both. A practical Mapbox pair is:

1. Mapbox Address Autofill on the shipping address, so city and postcode fill together.
2. Google Address Validation, Loqate Address Verify, or Smarty on place-order, so unverified or invalid addresses are caught while the customer is still on the page.
3. Local rules for missing house numbers, PO boxes, and postcode/country mismatches your warehouse will not ship.

Address Guard Pro treats autocomplete and validation as separate providers, so this mix is a normal production setup. Mapbox plus Google Address Validation or Loqate Address Verify is the usual combination.

What WooCommerce still will not do

Native checkout can:

• Require country, street, city, state, and postcode
• Offer shipping methods from those fields
• Copy billing into shipping

Native checkout cannot:

• Suggest real addresses as the customer types
• Fill city and postcode from a selected street
• Confirm that the building exists
• Standardize formatting for label purchase
• Keep original versus provider-normalized data on the order

Browser autofill is also not Mapbox. Autofill replays an address the customer saved earlier. It will fill a stale or incomplete address just as readily as a good one. A Mapbox suggestion is structured search data. It is still not proof that a carrier will accept the address.

How Mapbox autocomplete works at WooCommerce checkout

A working Mapbox address autocomplete flow has four steps.

1. The customer types in address line 1. Search does not run on every keystroke from character one. A minimum character threshold (commonly three) keeps suggestions relevant and keeps API usage down.
2. Search Box suggest runs. Address Guard Pro sends the query, a session token, the store language, and a country bias when one is available. Mapbox returns streets and addresses, not businesses or points of interest.
3. The customer selects a suggestion. Mapbox does not put the full postal address in the dropdown. A second Search Box retrieve request fetches street, house number, city, state, postcode, and country for that feature.
4. The checkout form is filled. Country is applied first when it changed, then street, city, state, and postcode. On classic checkout, WooCommerce refreshes the form so the correct state field appears. On Checkout Blocks, the cart store is updated so shipping methods can recalculate.

If the customer ignores the dropdown and types the rest by hand, checkout still works. Autocomplete is assistance, not a gate. Pair it with validation if you need to stop unverified addresses.

Country context should follow this order:

1. The country the customer selected at checkout
2. The countries you configured as autocomplete preferences
3. The provider’s own region setting
4. No restriction (Mapbox defaults)

Leaving the country list empty is fine while you test. Tighten it before you send paid traffic to checkout. Otherwise a suggestion from another market fills the form, then shipping zones and tax look wrong.

Set up Mapbox address autocomplete with Address Guard Pro

Address Guard Pro connects Mapbox Address Autofill to Checkout Blocks and classic [woocommerce_checkout]. You use your own Mapbox access token. The plugin does not bundle provider usage, so you keep control of Mapbox billing.

Address Guard Pro calls Mapbox from your WordPress server. The token is never exposed in checkout JavaScript.

Step 1: Create a Mapbox access token

In your Mapbox account, create or reuse a token that can call Search Box.

1. Enable Search Box API (suggest and retrieve) for the token.
2. Prefer a token that allows server-side requests.
3. Restrict the token to the Search products you actually use.

Watch the URL restriction. Address Guard Pro calls Mapbox from your server, so a token locked to HTTP referrers for your storefront domain can fail even when a client-side Mapbox map on the same site works. Allow the site’s outbound IP, or use a secret token with the matching restriction, rather than a public token that only accepts browser referrers.

Exhausted quotas, an invalid token, and a token without Search Box access surface as provider errors, not as a generic WooCommerce checkout failure.

Step 2: Connect Mapbox in WooCommerce

Go to WooCommerce → Address Guard → Providers.

1. Choose Mapbox Address Autofill as the autocomplete provider.
2. Enter the Mapbox access token.
3. Optionally set Autocomplete countries to the markets you ship to.
4. Click Test autocomplete provider.

Do not enable autocomplete on checkout until the test succeeds. A failed test usually means a missing token, a token restricted to the wrong product, a URL restriction that blocks server requests, or a billing account that has not enabled Search Box.

The tester sends a known-good query (a US street by default, or a German street if your region is DE) so you know Search Box can return suggestions before customers see the dropdown.

If you also want verification before payment, connect a Validation provider on the same screen. Mapbox can go live on its own. Validation is the second layer.

Step 3: Enable autocomplete on checkout

Go to WooCommerce → Address Guard → Checkout.

Recommended starting settings for a store that ships physical products:

• Enable address autocomplete: On
• Apply to shipping address: On
• Apply to billing address: Off, unless invoices or tax IDs depend on a precise billing street
• Minimum characters before search: 3

Shipping is the address that must be deliverable. Billing can stay as typed for most stores. If you enable both, test them independently: a customer may bill to a PO box and ship to a street address.

The minimum character setting controls when search starts. Three is a sensible default. Lower it only if your customers often search by very short building names. Higher values reduce API calls but make the dropdown feel late.

Step 4: Confirm the checkout type your store uses

Address Guard Pro supports:

• Checkout Blocks (the current WooCommerce checkout)
• Classic shortcode checkout ([woocommerce_checkout])

The Checkout screen shows which type it detected.

On classic checkout, autocomplete attaches to the standard WooCommerce address fields and re-initializes after checkout updates (for example after a country change).

On Checkout Blocks, autocomplete attaches by watching the address fields as they render. Selecting a suggestion updates the Blocks cart store so shipping methods and totals can refresh. Some block themes need extra CSS if the dropdown is clipped by an overflow rule. Check that on a phone-width viewport, not only on desktop.

Step 5: Pair Mapbox with validation and rules

Autocomplete reduces mistakes. It does not stop a customer who types a fake street and ignores the dropdown.

For a complete checkout address flow:

1. Mapbox helps the customer enter the address.
2. Validation checks the address against postal data.
3. Rules encode store policy: missing house numbers, PO boxes, postcode/country mismatches.

A practical first policy:

• Mapbox autocomplete on the shipping address
• Validation on the shipping address
• Checkout action: Warn customer
• Allow unverified addresses until you have reviewed a week of real orders
• Block missing house numbers and invalid postcode/country combinations once those rules are tested

How to turn that into a live workflow is covered in How to Validate Addresses Before WooCommerce Checkout. If your carriers cannot deliver to PO boxes or parcel lockers, add those restrictions separately: How to Block PO Boxes and Parcel Lockers in WooCommerce.

Step 6: Test the live checkout, not only the API

The provider test confirms the token. It does not confirm that your theme, checkout type, and country field work together.

On a staging site or in an incognito window, place a test order and check:

• Typing three or more characters in shipping address line 1 shows Mapbox suggestions
• Suggestions look like streets and addresses, not businesses or landmarks
• Keyboard navigation (arrow keys, Enter, Escape) works
• Selecting a suggestion fills street, city, state, postcode, and country
• Changing country first biases the next suggestions to that country
• Shipping methods update after the postcode is filled
• Billing is left alone if you disabled billing autocomplete
• A customer can still type an address without picking a suggestion
• The same flow works on a phone-width screen
• A token without Search Box access fails the admin test

Then enter a known-good address with the house number removed, and a postcode from another country, to confirm validation and rules still fire after Mapbox is on.

If the tester passes and checkout does not show suggestions, you are usually on the other checkout type (Blocks vs classic) or a theme is clipping the dropdown. Fix that before you send paid traffic.

Shipping address vs billing address

Apply Mapbox where a mistake is expensive.

Shipping address: turn it on. This is the address on the label. A wrong street or postcode here becomes a failed delivery.

Billing address: leave it off unless you have a reason. Card networks and tax engines are usually more tolerant of a slightly messy billing street than carriers are of a messy shipping street. A customer may also bill to a PO box, a registered office, or a finance team address that should not be “corrected” into a street.

If shipping and billing are the same, filling shipping is enough. If they differ, keep the two forms independent so a shipping suggestion cannot overwrite a billing address the customer meant to keep.

When Mapbox is the right autocomplete provider

Choose Mapbox Address Autofill when:

• You already have a Mapbox account and want checkout to use the same token
• You want search-quality street suggestions without putting Google Places on checkout
• You ship internationally and want country-biased Search Box results
• You want autocomplete on the server, with the access token kept out of checkout JavaScript
• You plan to validate with a different vendor (Google, Loqate, or Smarty)

Choose a different autocomplete provider (or mix) when:

• You already pay for Google Maps Platform and want Places plus Address Validation on one key. See Google Address Validation for WooCommerce.
• You already have a Loqate or GBG account and want Capture’s nested building-then-unit results plus Verify. See Loqate Address Validation for WooCommerce.
• Your catalogue is mostly US and you already pay for Smarty Autocomplete
• You only need local rules (PO boxes, missing house numbers) and are not ready to add an API

Address Guard Pro does not force a single vendor. Connect the network you already pay for, or the one that covers your shipping countries best.

Keep Mapbox API cost under control

You pay Mapbox directly. Address Guard Pro does not resell lookups.

Search Box bills suggest and retrieve separately. Every dropdown open can cost a suggest. Every selection costs a retrieve. Keep that predictable:

• Set minimum characters to 3 so search does not fire on the first letter.
• Limit autocomplete countries to the destinations in your shipping zones.
• Enable Mapbox on shipping only unless billing genuinely needs it.
• Do not leave the dropdown on a checkout you are not using (for example a leftover classic shortcode on a Blocks store).
• Watch Mapbox usage after launch, not only the admin tester.

A failed or empty search still consumes quota. A token that is valid but restricted to the wrong countries will look “connected” and still waste calls.

A Mapbox setup that works for most WooCommerce stores

If you want a default that improves checkout without surprising customers:

1. Enable Search Box (suggest and retrieve) on a Mapbox token that allows server-side requests.
2. Connect Mapbox Address Autofill in WooCommerce → Address Guard → Providers and run the test.
3. Limit autocomplete countries to the countries in your shipping zones.
4. Enable autocomplete on the shipping address only.
5. Set minimum characters to 3.
6. Connect a validation provider (Google Address Validation, Loqate Address Verify, or Smarty) and start with Warn customer.
7. Test on the checkout type your store actually uses, including a mobile viewport.
8. After a week of orders, add blocking rules for the mistakes that consistently delay dispatch.

The goal is not to make customers pick from a dropdown. It is to make the correct address the easiest thing to enter, then catch the rest before payment.

Common questions

Is Mapbox Address Autofill the same as address validation?
No. Autofill is autocomplete. Validation is a separate check against postal data. Mapbox fills the form. Google, Loqate, or Smarty checks the form before payment. Use both if you print shipping labels.

Does picking a Mapbox suggestion mean the address is validated?
No. A suggestion is a structured capture from Search Box data. Address validation is a separate verify step. Run both if you need deliverability, not only a filled form.

Do I need a Mapbox secret token?
You need a token that Search Box will accept from your server. A public token locked to HTTP referrers often fails. Address Guard Pro stores one Mapbox access token and never prints it in checkout JavaScript.

Why did the admin test fail when a Mapbox map on the same site works?
The map is usually a client-side request with a URL-restricted public token. Address Guard Pro calls Search Box from WordPress. Allow the server IP, or use a token that is not limited to browser referrers, and enable Search Box on that token.

Does this work with Checkout Blocks?
Yes. Address Guard Pro supports Checkout Blocks and classic [woocommerce_checkout]. Test the type your store actually runs, including a phone-width viewport so suggestions are not clipped.

Can I use Mapbox without a validation provider?
Yes. Expect more failed labels, because customers can ignore the dropdown and type. Mapbox is the cheaper way to reduce typos. Validation is how you catch the rest.

Can I use Mapbox with Google or Loqate validation?
Yes. Autocomplete and validation are separate choices. Mapbox suggestions plus Google Address Validation or Loqate Address Verify is a normal mix.

Will Mapbox replace shipping zones?
No. Shipping zones decide which methods to offer. Mapbox helps the customer enter country, state, and postcode so those zones can calculate. It does not decide whether the address is deliverable.

What if Mapbox is down or over quota?
Checkout should still accept a typed address. Set validation provider errors to Mark for review if you also run a verify step, so an API outage does not become a payment failure. Do not let a Search Box quota problem freeze place-order.

What about API cost?
You pay Mapbox directly. Keep costs down by setting a minimum character threshold, limiting countries, and avoiding autocomplete on billing unless you need it.

Help the customer enter the address once, correctly

WooCommerce will accept any address that fills the required fields. Mapbox address autocomplete for WooCommerce makes the complete, consistent address the path of least resistance: the customer types a street, picks a match, and city, postcode, and country fill in together.

Add validation when you need to check that address before you take payment. Add rules when your carriers cannot serve PO boxes, lockers, or streets with no house number.

Learn more about Address Guard Pro, or start with the setup guide: Get Started.