Table of Contents
Address Validation and Classification
ShipStream's address validation and classification system uses uses third-party systems to automatically detect invalid addresses, in some cases make corrections to invalid addresses and also determine the classification of an address. This can save you time and money as well as keep your customers happy by:
- aiding in proper shipping method selection (see Rate Shopping)
- avoiding costly fees like residential surcharges for FedEx Ground
- preventing routing delays that frustrate your customers
Address Classification
ShipStream supports the following address classifications:
- Residential
- Commercial
- Post Office
- Military/Diplomatic
- Unknown
In some cases this can be very important, for example some carriers and services may not be authorized to ship to Post Office locations and only USPS can ship to US Military addresses. Additionally, some services like FedEx Home Delivery will not ship to Commercial addresses or will add a surcharge.
classification field).Address Validation
Of course, one cannot reliably classify an address that is invalid so address validation is closely tied to the address classification system. If the address classification is Unknown then either the validation has not yet been attempted, has been skipped or has already failed.
There can be many reasons for address validation failure, but in general, "garbage-in, garbage-out" so always try to provide the best data possible. The customer should know their own address best so if possible use techniques to allow the end-customer to validate their address even before the order is submitted. If you're already doing this, you can submit your orders via the API and Import with the is_valid flag which will tell ShipStream not to make any changes to the address as it should be considered as already correct.
Automatic Validation and Classification
Your ShipStream instance comes already setup to perform address validation and classification when the classification is Unknown. This process should occur within the first minute after an order is submitted. If the online validation has not occurred yet or failed the address will appear like this:
The results will be logged in the order history (click the History tab in the left sidebar on the order page). Clicking the Validate Address button will present a page where the user can view the address on a map and choose a classification, edit the address or hold the order.
However, if the online validation is successful, the order page will reflect the update and the History tab will provide details on what was changed and how:
If the address was modified in any way, the original is visible in the History and on the order page by clicking Show Original Address.
Address Validation Failures
When the automatic validation fails, there are several configuration options you may want to pay attention to:
Hold on Address Validation Failure
Set System > Configuration > Shipping > Address Validation > General > Hold on Address Validation Failure to Yes to put the order on hold with a special "Invalid Address" status. This requires a user to unhold the order either by choosing an address classification, editing the order address or clicking Unhold to ignore the validation.
Email Notifications
If you enable an email notification at System > Configuration > Shipping > Email Notifications > Order Address Validation Failure > Enabled, the system will send an email to the configured address so that a user can easily click a link in the email to choose a classification or take other actions.
Classification Fallback
There are some situations where an Unknown address classification can throw a wrench in your operations so you may wish to default to a fallback to avoid breaking your stride. These can be configured here to "Default to Residential" or "Default to Commercial", but the default is "Require Update":
- System > Configuration > Warehouse > Scanner > Bulk Fulfill Order > Not-Classified Addresses
- This prevents errors about address validation being presented to the packer when packing out Bulk Fulfill Orders.
- System > Configuration > Warehouse > Operations > Bulk Fulfill Order > Batch Label Generation Not-Classified Addresses
- This prevents errors about address validation from causing labels to be skipped when generating all labels at once for Bulk Fulfill Orders.
Webhooks
You may also subscribe to a Webhook to receive an HTTP request to the URL of your choosing with information about the order which incurred an address validation failure. See order:address_validation_failed for more information.
Manual Corrections
Any time you Edit an address and choose a known classification this will be assumed to be good infomration and remembered for all future orders to this address. If you believe a mistake was made by the system's online validation, clicking Revert will change the order address back to the original and permanently record the original address as the correct address so that it will not be modified automatically in the future.
After an order is completed or canceled you can no longer edit the order address, but you can report a correction to avoid future errors for the order's address by clicking Report Correction.
Which will present this form:
And record in the order history a message for the reported correct address:
