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. The address is stamped with a validation date when saved. 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
- 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
- Validation date stamped on saved addresses
- FedEx API credentials stored encrypted
- Rule-based and deterministic – no AI, no service other than FedEx
- Fully translatable customer-facing messages
Versions
See CHANGELOG.public.md. 1.5.2 is a fix release with two headlines. First,
a shopper is never left on the shipping step with Next switched off: that used
to happen whenever the extension decided not to send the address at all – an
incomplete field, or a country where Magento itself makes the postcode
optional, such as Hong Kong and Macao – and whenever the request was sent but
did not come back, from an expired session, a server error, a timeout or a
firewall answering instead of the store. A three-character postcode is no
longer refused before the request is even made, which had stopped shoppers in
Iceland, the Faroe Islands, Oman and Papua New Guinea. Second, 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 used to reject the whole
request, so the street, the city and the postcode went unchecked too. The
region code is now left out when it is too long to send and the carrier
resolves the region itself; where its answer does not match the form Magento
stores, the region the customer entered is kept rather than cleared. 1.5.1 is a fix release, and the headline is that
address validation can no longer cost an order: a shopper whose address FedEx
cannot validate – anyone shipping to India or mainland China among others – used
to be unable to leave the shipping step at all, because nothing was offered for
them to choose and Next returned them to the same check. The step now always
proceeds, whatever validation had to say. It also stops rejecting a comma in a
city name, measures city and street lengths in characters rather than bytes,
offers corrected international addresses again (verified for Ireland, the
Netherlands, Canada and Spain, where they had been discarded), and accepts an
address without a postcode in the countries where Magento itself treats one as
optional. Requires setup:di:compile. 1.5.0: the country prefix Magento stores
in front of a region code is removed before the request, so addresses in some
two dozen countries can be validated at all. 1.4.4 is packaging only: the declared Magento
compatibility now names the framework major this extension is tested against
rather than also claiming a future one. 1.4.3: at guest checkout, pressing Next with an incomplete shipping address now highlights the missing fields and blocks the step instead of leaving the button disabled with no explanation. Builds on v1.4.2 (internal code-quality work, no behaviour change), v1.4.1 (FedEx error responses are surfaced as intended rather than as a server error; installable on PHP 8.5 across 2.4.7 – 2.4.9) and v1.4.0 (apartment / suite lines are never dropped from a suggested address, on every address line; a clear, non-blocking message replaces raw service errors when validation is temporarily unavailable; credential fields are masked in the admin and no longer re-encrypted on save). v1.3.0 introduced real-time FedEx validation at checkout, account and admin order creation, the standardized-suggestion popup, US city correction, EU region-code normalization and encrypted API credentials.
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.
- 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 validation date stamped on saved addresses.
- 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.2. The module contains no working 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.