Zum Inhalt springen
Address Validation iO

Diese Dokumentation gibt es nur auf Englisch.

Erste Schritte

How a check works

The steps of an address check, the four results, the Strict, Balanced and Loose modes and the free pre-check.

Every address check runs the same steps on every platform and ends with one of four results. Knowing the steps helps you understand why an address got its result.

The steps

  1. Address rules. Your own address rules run first. A "Block" rule makes the address Invalid, a "Skip validation" rule leaves it Not checked. Neither asks a provider.
  2. Pre-check. A free look for obvious problems, such as a missing house number or a phone number in the street line (see below). A serious problem makes the address Invalid in every mode, without asking a provider.
  3. Stored answer. If your shop checked the same address before, AVIO may reuse that answer instead of asking the provider again.
  4. Provider. Otherwise AVIO asks the provider set for the country. If it fails, times out or is unsure, the backup provider is asked once, where one is set and covers the country.
  5. Mode. The country's mode (Strict, Balanced or Loose) turns the provider's answer into a result.
  6. Final adjustments. A PO box or parcel locker the provider spots is still Invalid if you block that kind of address. A "Flag for review" rule turns Valid into Needs checking.

The four results

Result API value What it means
Valid valid The provider confirmed the address.
Needs checking warn Probably a typo or a missing part, or the provider suggested a correction. The customer should check the address.
Invalid invalid The address couldn't be verified, or it breaks a rule such as a missing house number.
Not checked skipped AVIO didn't check the address: the country is switched off, a "Skip validation" rule matched, or no provider gave a usable answer.

Not checked doesn't mean the address is bad. It means AVIO has no opinion on it.

What follows each result depends on the platform. On Shopify, for example, Needs checking and Invalid trigger a correction request, and only Invalid can block checkout or hold fulfillment. See Order checks. With the API, your own code decides; see Validate an address.

Customers don't see these names. They read texts such as "Please check your shipping address".

Validation modes

The mode sets how strictly AVIO treats a provider's corrections. You set it per country, next to the provider. Balanced is the recommended mode.

What the provider reports Strict Balanced Loose
No problem Valid Valid Valid
A small correction, or a part it filled in Invalid Needs checking Needs checking
A different street, house number, city or postal code Invalid Invalid Needs checking
Street or house number missing Invalid Invalid Not Invalid for this alone
Unsure (ambiguous match) Invalid Needs checking if only one provider answered and nothing is missing, else Invalid Needs checking
No match Invalid Invalid Invalid

Strict also needs the provider to confirm the address down to the house number. Cosmetic differences, such as "Str." for "Straße", capital letters or accents, never count as a correction.

Pre-check problems and "Block" rules make an address Invalid in every mode, including Loose.

Note: Changing the mode changes every address in that country. Try a few real addresses first: the Shopify app has "Test an address" on the Providers page.

The pre-check

The pre-check is free and runs before any provider is asked. It looks at the street, apartment, city, postal code and state fields.

These problems make the address Invalid in every mode, and no provider is asked:

Problem API issue code
An email address in an address field email_in_field
A link (URL) in an address field url_in_field
A phone number in an address field phone_in_field
The street or city is empty empty_required_field
No house number where one is required (see below) missing_house_number
A German Packstation or post office without the DHL Postnummer parcel_locker_without_number
A PO box, where you block PO boxes po_box_blocked
A parcel locker or pickup point, where you block them parcel_locker_blocked

These findings are reported but don't decide the result on their own:

Finding API issue code
The postal code is also typed into the street line (Germany, Austria, Switzerland, the Netherlands) zip_in_address1
A PO box (accepted) po_box
A parcel locker or pickup point (accepted) parcel_locker
One of your address rules matched address_rule

House numbers

In 14 countries an address without a house number fails the pre-check: Germany, Austria, Switzerland, Liechtenstein, the Netherlands, Belgium, Luxembourg, Denmark, Poland, the Czech Republic, Slovakia, Hungary, Slovenia and Croatia. The number counts as missing when the street and apartment lines contain no digit at all. PO boxes and parcel lockers are exempt.

A number written as a word, or typed into the name or company line, isn't found.

PO boxes and parcel lockers

AVIO recognises PO boxes, parcel lockers and pickup points by keywords, country by country. You decide per country whether to accept or block each kind. A German Packstation, Postfiliale or Paketshop needs the customer's DHL Postnummer (6 to 10 digits). With it, AVIO accepts the address without asking a provider, unless you block parcel lockers for Germany. See Address rules and delivery points.

Providers and the backup provider

AVIO works with several address data providers: Loqate, Google Address Validation, Postcode.eu and Smarty. Each country has a provider, an optional backup provider and a mode. AVIO maintains a recommended setup, and you can choose your own per country.

The backup provider is asked once, only when the main provider fails, times out or is unsure. If neither gives a usable answer, the address is Not checked. A provider outage never blocks checkout or your orders.

If you switch a country off, its addresses aren't sent to a provider and show as Not checked. Your address rules and the pre-check still run.

Stored answers

AVIO remembers provider answers per shop, so a repeat address needs no new provider call. An answer is stored for the address alone (street, apartment, city, postal code, state and country); names, company and phone play no part. Changing the country's provider, backup provider or mode means the next check asks the provider again. Your address rules and delivery point settings always apply on top, so a change to them works at once.

Google answers are kept for 30 days, Loqate, Postcode.eu and Smarty answers for 180 days.