Notes from delivery
When your address validation provider fails mid-checkout
A soft failure with no error message is the worst class of bug. Nothing in the logs, nothing you can reproduce at your desk, and orders quietly not happening.
The report came through support, not monitoring, which should have been the first clue. Customers were ringing to say the site would not accept their address. No error in the logs, no failed transaction recorded, and nothing anyone could reproduce from the office.
That combination is characteristic and worth recognising, because it points at a specific kind of problem: a third-party service returning something the storefront is treating as a stop, without either side considering it an error.
Why it does not show up
Address validation providers do not only return valid or invalid. They also return degrees of uncertainty: no exact match, partial match, match with low confidence. Those are legitimate responses to a legitimately ambiguous input, and for a lot of addresses they are the correct answer.
The failure happens in how the storefront interprets them. If the code treats anything that is not a confident match as a rejection, and rejects without a message, then a customer with a regional address that the provider cannot confidently resolve simply cannot proceed. Nothing errored. The system did exactly what it was told. The order just did not happen.
Nothing was broken. Everything behaved as implemented. That is what made it hard to find.
It also explains the geography of the complaints. Urban addresses match confidently and never see it. Rural and regional addresses do not, which in a trade context often means the highest-value accounts are the ones hitting it.
Instrument the failure path
You cannot fix a distribution of inputs you cannot see. The first change is not a fix at all: log every non-confident response together with the shape of the address that produced it. Not the customer’s details, the shape. Postcode range, state, whether a unit number was present, that sort of thing.
Two weeks of that turns an anecdote into a list. And the list is the thing you need next, because it is the only honest test set.
Benchmark against real failures, not a demo set
Every validation provider has a demo that works. Of course it does, it is built from addresses their data resolves cleanly.
Take your logged failures and run them against the alternatives. This is a couple of hours of work and it is the only part of the exercise that actually tells you anything. In our case one provider handled the regional cases the incumbent could not, and two others failed in the same places, which would have been an expensive thing to discover after switching.
Worth checking while you are there: what each provider returns for a genuinely bad address. A service that confidently resolves nonsense is worse than one that admits uncertainty, because now you are shipping to somewhere that does not exist.
Fallback as a second attempt
The fix I would recommend is not a replacement. It is an order of attempts:
- Primary provider. Unchanged, still handling the great majority of traffic.
- Fallback provider, triggered only on a non-confident response from the first.
- Manual entry, with a clear message, if both are uncertain. The customer knows their own address. Let them assert it.
That third step is the one people leave out, and it is the one that guarantees the checkout can always complete. Validation exists to reduce delivery failures, not to prevent orders. When it starts doing the second thing, it has stopped being a feature.
The wider lesson
The specific bug is not that interesting. What I took from it is a question I now ask about every third-party dependency during scoping: what does this service return when it is unsure, and what do we do with that?
Most integrations handle success and handle hard failure. The middle case, where the service answers but does not commit, is where the quiet problems live. It is rarely in the acceptance criteria, and it is almost never in the demo.
Written from delivery experience on ecommerce storefronts. No client, provider or engagement is named, and the technical detail is generalised.
I am Abhishek KC. I manage delivery on client software projects from Kathmandu, working with teams in Australia and the US.
More about my work