Getting started
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
- 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.
- 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.
- Stored answer. If your shop checked the same address before, AVIO may reuse that answer instead of asking the provider again.
- 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.
- Mode. The country's mode (Strict, Balanced or Loose) turns the provider's answer into a result.
- 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.