Zum Inhalt springen
Address Validation iO

Diese Dokumentation gibt es nur auf Englisch.

WooCommerce

Set up the WooCommerce plugin

Install the Address Validation iO plugin for WooCommerce, connect it with your API key and choose how checkout and orders are checked.

The plugin "Address Validation iO for WooCommerce" checks shipping addresses at checkout and after every order. Customers see "Did you mean …?" with a corrected address and can fix their own typos with one click. It works with the block checkout and the classic (shortcode) checkout, and with HPOS (custom order tables).

Note: The plugin is not in the WordPress plugin directory yet. To get the plugin and an account, use the WooCommerce contact form.

Requirements

  • WordPress 6.5 or newer
  • WooCommerce 8.0 or newer
  • PHP 8.1 or newer
  • An Address Validation iO API key and API URL

Install

  1. Get the plugin zip from us via the contact form.
  2. In WordPress, go to Plugins → Add New Plugin → Upload Plugin, upload the zip and activate it. WooCommerce must be active.

The plugin adds WooCommerce → Address validation with the tabs Overview, Settings, Providers, Logs, Analytics, Usage and Help.

Connect

We set up your shop and send you an API key and the API URL. The key starts with avk_.

  1. Go to WooCommerce → Address validation → Settings → Connection.
  2. Paste the key into API key and the URL into API URL, then save.
  3. The status line now reads "Connected to …" with your shop's name. Test connection checks the key and URL again at any time.

The key stays on your server and is never shown to customers. After saving, the field shows "Saved key ending in …" with the last four characters; leave it empty to keep the saved key.

Nothing is sent and nothing is checked until both the key and the URL are saved.

Test shops

A new shop can be set up as a test shop. It answers from test data and nothing is billed. The Settings page then shows a "Test shop" badge. We switch a shop between test and live; you can't change it yourself.

Configure

Everything except the API key and the API URL is stored in Address Validation iO, so our support sees the same values you do. The plugin picks up changes within about 5 minutes, or at once when you open the Settings tab.

Checkout

Address check at checkout controls how the checkout reacts to an address that looks wrong:

Option What happens
Off No address check at checkout.
Ask the customer to check (recommended) The customer sees the suggestion. Clicking "Place order" again keeps the address they entered. This is the default.
Block addresses that can't be delivered Addresses that can't be delivered stop the order. Addresses that only need a look can still be kept.

The checkout rules in the same section stop the order in both "Ask" and "Block" mode:

  • Require a house number in: countries (up to 50) where an address without a number in the street lines can't be ordered.
  • Check the postcode format in: countries where the postcode must match the country's format.
  • Longest address line: characters per address line, for carriers with short label fields. 0 turns it off.
  • Throwaway email addresses: block disposable email addresses at checkout.

Address rules you set up with us (block, flag, rewrite or skip an address by what it contains) also apply at checkout. A rule that blocks an address stops the order with its own message and marks the affected field.

Delivery points

Under Settings → Delivery points you choose per country whether P.O. boxes and Parcel lockers are allowed or blocked. "All other countries" is the default row; a country row overrides it. Block sends customers back to enter a street address.

Orders

Setting Default What it does
Check new orders On Checks the shipping address of every new order and shows the result on the order page.
Billing address On Also sends the billing address when an order ships somewhere else.
Address line 2 Off Ignores address line 2 (apartment, c/o) when checking.
Address changes by customers Empty Hours after the order until customers can no longer correct the address (1 to 1,440). Empty means until the order is completed.

Customer contact

Check email addresses and Check phone numbers also check the customer's email address or phone number on new orders. Both are off by default, and each check is billed. You can choose the provider for each check and an optional fallback; the list shows your price per check. See Pricing.

Holds and customer

Setting Default What it does
Put orders on hold On Sets orders with an address that can't be delivered to On hold until it's fixed.
Check saved addresses On Checks an address when a customer saves it in My Account.

Providers

By default your shop follows our recommended setup: a data provider per country and, where a second provider covers the country, a backup. Our updates to that setup reach your shop automatically.

On the Providers tab you can choose the provider per country, switch a country off and use Test an address to try any address. A country you change is marked Custom and no longer receives our updates; Use recommended brings it back.

What happens at checkout

When the customer places an order, the plugin sends the shipping address (or the billing address when there is no separate shipping address) to Address Validation iO.

  • Valid address: the order goes through.
  • Address needs a look: a notice asks the customer to check it, with "Did you mean …?" and the suggested address when there is one.
  • Checkout rule broken: the order stops with a specific message, for example "Please add your house number."

If Address Validation iO is slow or can't be reached, checkout waits at most three seconds and then lets the order through. The checkout rules come with our answer, so they don't apply during an outage. Your store keeps selling either way.

Checks at checkout are not counted on your Usage tab.

What happens after the order

Every new order is checked in the background (when Check new orders is on and the order has a usable address). If Address Validation iO can't be reached, the check is retried after 5 and after 30 minutes.

  • The order page gets an Address check box with the result, the suggestions, Check again and a button to use a suggested address. A link opens the order's history.
  • The orders list gets an Address column.
  • A result that needs a look adds an order note. Every fix and re-check is noted too.
  • With Put orders on hold, a Processing order with an address that can't be delivered goes On hold, once per address, with no time limit. It returns to Processing when the address is valid, fixed or confirmed.

Editing an order's address in the admin checks it again.

Customers fix their own address

On the order confirmation page and in My Account, the customer sees "Please check your shipping address" with up to three suggested addresses. They click Use this address or My address is correct. The order is updated and the hold released. Customers pick from the suggestions; they don't type a new address there.

The My Account dashboard also tells customers which orders need an address check.

Logs, analytics and usage

  • Overview: this month's numbers and a 30-day chart.
  • Logs: every check, correction and settings change of the last 90 days, with filters, and each order's history.
  • Analytics: checks, valid addresses, corrections, estimated savings, results and top countries. Enter your cost per failed delivery to estimate savings.
  • Usage: this month's checks, your prices and the last 12 months.

Privacy and data

The plugin sends the addresses to check and the order number, plus the customer's email address and phone number only when you turn those checks (or the throwaway-email rule) on. Order data is kept for up to 180 days after the last check, logs for 90 days.

The WordPress personal data eraser also deletes Address Validation iO's copy of that customer's orders. The plugin adds suggested text for your privacy policy.

Uninstall

Deleting the plugin in WordPress (Plugins → Delete) removes its options, caches and queued jobs. The results stay on your orders as order meta and notes. The plugin also tells Address Validation iO, which then erases your store's order checks and logs. The rest of your store's data, such as your settings, is deleted within 30 days.

Troubleshooting

Nothing is checked

Press Test connection. Usual causes: the key or URL is missing or mistyped, or Address check at checkout or Check new orders is off. A test shop gets test answers. If the connection test fails and the values look right, contact us.