FedEx Address Validation
/
Undeliverable and mistyped shipping addresses cost merchants money – failed deliveries, re-ship fees, and support time. FedEx Address Validation checks each address in real time against the FedEx Address Validation REST API and offers the customer a standardized, deliverable version before the order is placed.
The validation runs in three places: the storefront checkout, the customer account address book, and the admin Create Order screen. When an address can be improved, a popup presents the FedEx-standardized suggestion next to what the customer entered, and the customer chooses which to use. Each validation outcome is deterministic – it comes straight from FedEx's response plus the extension's own correction rules, with no guessing.
Beyond a plain FedEx lookup, the extension adds a US city correction step: FedEx confirms that a ZIP and state exist but does not verify that the city spelling matches the ZIP, so an address like "New York, NY 30301" passes even though 30301 is an Atlanta ZIP. The extension cross-checks the city against its bundled US ZIP database and corrects the spelling when they disagree. It also normalizes EU region codes (for example a German or Spanish province name to its FedEx-expected code) and preserves apartment and suite lines, so a unit number the customer entered is never dropped from the standardized suggestion.
You enable validation independently for each surface (checkout, account, admin), control whether customers may keep their original address, and choose how suggestions are presented. A saved address that FedEx returns unchanged, with no warning, goes through without the popup, and a correction the customer takes for a saved address goes into the order without adding a copy to the address book. Each saved address carries the date it was last saved outside the admin, which one setting can use to skip checking it again; shoppers never see that date. FedEx Address Validation is a rule-based, deterministic, on-premise extension: it uses your own FedEx developer credentials – stored encrypted in Magento's configuration – and calls no service other than FedEx. It runs on the Luma theme.
Key Features
- Real-time address validation against the FedEx Address Validation REST API
- Runs at storefront checkout, customer account address book, and admin Create Order – each independently toggled
- Standardized-address suggestion popup; customer chooses original or corrected; a saved address FedEx returns unchanged, with no warning, passes without it
- US city correction against a bundled ZIP database (catches mismatches FedEx accepts)
- EU region-code normalization (province name to FedEx code)
- Apartment / suite line preservation – the unit number is never dropped from a suggestion
- Saved addresses record when they were last saved outside the admin, never shown to shoppers
- FedEx API credentials stored encrypted
- Rule-based and deterministic – no AI, no service other than FedEx
- Fully translatable customer-facing messages
Versions
Fix release for checkout reloads: a reload on the payment step no longer brings back the address dialog or loses the selected address, and FedEx's correction for a saved address keeps more of the recipient's details. Ships License Agreement 1.1.0.
Show details Hide details
Changed
- The checkout template no longer has a separate branch for themes whose code contains "Hyva". That branch output markup for a script the extension has never shipped, in place of the setup that runs the address check. Every theme now gets the same setup, and for every other theme the checkout page is byte-for-byte what it was. This adds no Hyvä support – Hyvä storefronts remain unsupported.
- The License Agreement is now version 1.1.0, effective 2026-10-08. Section 7.1 also lets the agencies or developers a customer engages access the extension on the customer's behalf, on the same condition as its employees and contractors: bound by confidentiality and use restrictions at least as protective as the Agreement's. No other term changed.
Fixed
- Reloading checkout on the payment step no longer brings the address dialog back over it. The extension checked the address again on every page load, whichever step was showing, so after a reload its dialog covered "Place Order" until it was closed – and a suggested address chosen there changed what "Ship To" showed but not where the order shipped. The check now waits for the shipping step: it runs as before when checkout opens there or the shopper goes back to it, and not at all when the order is placed from the payment step.
- The shipping address a shopper selected stays selected after a reload. Checkout fell back to the default address – in "Ship To" and in the validation – while the order still went to the address the shopper had picked. The selection is now remembered the way Magento itself remembers it, whether or not address validation is switched on.
- Choosing the suggested address for a saved address now also keeps the recipient's prefix, middle name, suffix, fax and VAT number. First name, last name and company were already kept; these five came from Magento's address form. They now come from the saved address, whether or not the store shows those fields.
Upgrade notes
- There is no database change and no new PHP code. The checkout's scripts
changed: in production mode, run
bin/magento setup:static-content:deployand flush the cache, or shoppers keep the previous scripts.
Fix release for saved addresses at checkout: FedEx's correction no longer adds a copy to the address book or changes the recipient, an unchanged address needs no dialog, and the extension's date is no longer shown to the shopper.
Show details Hide details
Fixed
- Choosing the suggested address for a saved address no longer adds a copy of it to the address book. The correction was applied through Magento's own "New Address" form, which saves with "Save in address book" ticked, so placing the order stored a second entry beside the one the shopper had picked. The corrected address still goes into the order, and the address book stays as it was. An address the shopper adds by hand is still saved, or not, exactly as that box says.
- The recipient's name and company are kept when that correction is applied. The form started from the account holder's name and an empty company, so a saved address for someone else left checkout under the wrong name. First name, last name and company now come from the saved address. Middle name, prefix, suffix and VAT number, where a store uses them, still come from Magento's address form.
- A saved address that FedEx returns unchanged, with nothing to warn about, is accepted without a dialog. The shopper was asked to choose between two identical lines, and keeping their own drew a warning that the address was unvalidated. Until now only "Skip / Hide validation if entered address correct?" avoided this, and that setting also stops every saved address that carries the extension's date from being checked again. Addresses typed at checkout, a guest's included, still follow the setting, and a suggestion that carries a warning is still shown.
- The date the extension keeps on saved addresses is no longer printed in the shopper's address at checkout, where it appeared as an extra line in the billing address on the payment step and under "Ship To". It is still stored and still read by "Skip / Hide validation if entered address correct?". Integrations that read customer addresses through Magento's REST or GraphQL APIs still receive it.
Upgrade notes
- There is no database change. Run
bin/magento setup:upgradeand, in production mode,bin/magento setup:di:compile: the date is hidden by a new storefront plugin. - Address-book copies that earlier versions created this way are not removed.
Fix release: the shipping step can always be left, three-character postcodes are accepted, and addresses in eight more countries are checked.
Show details Hide details
Fixed
- A shopper could be left on the shipping step with the Next button switched off and no way to switch it back on. It happened whenever the extension decided not to send the address to FedEx – an incomplete field, or a country such as Hong Kong or Macao where Magento itself treats the postcode as optional – and whenever the request was sent but did not come back: an expired session, a server error, a timeout, a firewall answering instead of the store. In both cases the shopper can now continue, the shipping methods are shown, and no empty dialog is opened over the buttons. This is not the carrier being unable to answer, which was already handled in 1.5.1; it is the connection between the browser and the store.
- A three-character postcode is no longer refused before the request is made. The storefront demanded four characters while the extension's own rule – and Magento's – accept three, so an address such as "101 Reykjavík" stopped the shopper at checkout. The same countries are affected in the address book: Iceland, the Faroe Islands, Oman and Papua New Guinea.
- Addresses in eight more countries are checked at all. Where Magento's region code is longer than the two characters FedEx accepts – Australia, Belgium, Colombia, Finland, Latvia, Mexico, Paraguay and Peru – the carrier rejected the entire request, so the street, the city and the postcode went unchecked too and the shopper was shown a "couldn't verify this address" row. The region code is now left out of the request when it is too long to send, and the carrier resolves the region itself. Where its answer matches the form Magento stores – Australia, Finland, Mexico – that is the region you get back; where it does not, the region the customer entered is kept rather than cleared, because an emptied region select is a save Magento refuses in exactly these countries. In those five countries the region is preserved, not confirmed; what the carrier verifies is the street, the city and the postcode.
FAQ
A shipping address that is complete is not the same as a shipping address that exists. Adobe Commerce and Magento Open Source check the first and have no way to check the second, so a mistyped street number or a city that does not belong to its postcode goes through the checkout, onto a label, and comes back as a failed delivery, a re-ship and a carrier address-correction surcharge.
This extension asks the carrier before the order is placed. Every address is checked in real time against the FedEx Address Validation REST API using your own FedEx developer credentials, and where FedEx can improve it the customer is shown the standardised version beside what they typed and chooses. The work that stops being manual is the part after the parcel comes back.
- You ship with FedEx and you pay their address-correction fees. The fees are the measurable version of this problem, and they appear on an invoice you already receive.
- You sell into the United States. The city-against-postcode check is the part of this extension with no equivalent elsewhere, and it is US-specific.
- Your staff type addresses. Telephone and B2B orders created in the admin panel get the same check as the storefront – a surface the direct competitor does not cover.
- You sell into Europe, Australia or Latin America. Magento stores some region codes in a form FedEx rejects outright, which silently leaves the whole address unchecked. Releases 1.5.0 and 1.5.2 handle both shapes of that problem.
- You run the Luma theme. That is the only storefront this release supports.
- You do not ship with FedEx. This calls FedEx and nothing else. For UPS, USPS or a dedicated address-data service there are listings on the Adobe Commerce Marketplace that do exactly that, from EcomPlugins among others.
- Your storefront is Hyvä. There is no Hyvä integration in this release.
- Your checkout is a third-party one. One Step Checkout and similar replacements are not tested and not claimed. The direct competitor does claim them; if that is your checkout, buy theirs.
- You only ship inside one European country. A national address service – Postcode.eu in Benelux, Ideal Postcodes in the UK – will beat a carrier lookup on local data, and both are free to install.
- What you actually need is residential-versus-commercial classification. That is a different question and a different product.
- Real-time validation on three surfaces, each switched on independently: storefront checkout, the customer account address book, and admin Create Order.
- A suggestion popup showing the FedEx-standardised address beside the original. You control whether it opens automatically, whether the customer may keep their original, and whether an address FedEx cannot judge is shown or passes silently. A saved address FedEx returns unchanged, with no warning, goes through without it, and a correction taken for a saved address goes into the order without adding a copy to the address book.
- US city correction. FedEx confirms that a postcode and state exist but not that the city spelling matches – "New York, NY 30301" passes, and 30301 is an Atlanta postcode. The extension cross-checks against a bundled database of 29,470 postcode-to-city entries covering all 51 states and territories.
- Region-code normalisation. The country prefix Magento stores in front of a region code is removed, and a region code longer than the two characters FedEx accepts is left out so the carrier resolves it – which is what makes addresses in Australia, Belgium, Colombia, Finland, Latvia, Mexico, Paraguay and Peru checkable at all.
- Apartment and suite preservation. The unit line is carried onto the standardised suggestion across every address line, never dropped.
- A date on every saved address, set each time it is saved outside the admin, which one setting can use to skip checking it again. Shoppers never see it.
- Encrypted credentials and a sandbox mode, with OAuth tokens cached for thirty minutes so a busy checkout is not re-authenticating.
- A checkout that always proceeds. An incomplete field, a country FedEx does not cover, an expired session, a timeout, a firewall answering instead of the store – none of them can strand a shopper on the shipping step.
- Fully translatable customer-facing messages.
- It is not a Hyvä extension. Luma only in 1.5.4. The module contains no Hyvä storefront integration and none is claimed.
- It does not classify addresses. Residential versus commercial is not a question it answers; a competing listing does, separately and at extra cost.
- It is not a carrier integration. No rates, no labels, no tracking, no pickup scheduling.
- It has no bulk mode. There is no console command, no cron job and no web API, so an existing address book is not validated retroactively – addresses are checked when someone touches them.
- It cannot validate what FedEx will not. Mainland China is not supported by the carrier's validation service; the honest outcome there is that the address is skipped, not that it is confirmed.
- It is not a compliance or deliverability guarantee. FedEx's answer is FedEx's answer, and a well-formed address in a database can still be an empty lot.
- It sends the shipping address to FedEx. That is the entire function, it uses your own FedEx account, and no other external service is contacted – but if the address may not leave your infrastructure, this is not the extension.