Address recommendations without breaking checkout state
Keep the entered address and provider suggestion separate, discard responses for old edits, and save only the buyer's accepted choice.
In this guide
- Entered address
- Current validation
- User choice
- Accepted address
- Recalculate delivery
The helpful suggestion that erases a suite number
A buyer enters a delivery address with a building and suite. An external validator returns a standardized version. The checkout replaces the form immediately, and the suite disappears. The service improved one representation while losing information that mattered to the shipment.
Keep the entered address, suggested address, and accepted address as distinct states. A provider recommendation is evidence for the user to consider, not automatic permission to overwrite their input. Decide which changes can be accepted silently, if any, and which require explicit comparison under the business's delivery policy.
Validate the current input revision
Assign a revision to the address being edited. Send a normalized copy for validation and associate the response with that revision. If the buyer changes the form while the request is in flight, discard the old recommendation rather than presenting it as a suggestion for the new address.
Preserve fields the provider does not understand or return. Country and region identifiers may need mapping to the commerce platform's model; display labels are not always suitable keys. Resolve mappings through a bounded, version-appropriate adapter and distinguish unsupported countries from invalid addresses.
Model the recommendation lifecycle
Keep one AddressRecommendationState for the address being edited. Call edit when its fields change. Before sending the provider request, call beginValidation and retain its revision. After mapping the provider response, call receive with that revision and the proposed Address.
When the buyer decides, call choose. The method returns the accepted address and clears the recommendation. Save that result through the existing authorized checkout path, then recalculate shipping and tax. The compact Address model includes line2 for suite information; carry any company field and existing address ID separately in your checkout model.
checkout/address-recommendation-state.ts typescript
export type Address = Readonly<{
line1: string; line2: string; city: string;
region: string; postalCode: string; country: string;
}>;
export type Recommendation = Readonly<{
revision: number; original: Address; suggested: Address;
}>;
export class AddressRecommendationState {
private revision = 0;
private entered: Address;
private recommendation: Recommendation | null = null;
constructor(initial: Address) { this.entered = { ...initial }; }
edit(address: Address): number {
this.entered = { ...address };
this.recommendation = null;
return ++this.revision;
}
beginValidation(): Readonly<{ revision: number; address: Address }> {
return { revision: this.revision, address: { ...this.entered } };
}
receive(revision: number, suggested: Address): boolean {
if (revision !== this.revision) return false;
this.recommendation = {
revision, original: { ...this.entered }, suggested: { ...suggested }
};
return true;
}
choose(useSuggestion: boolean, allowOriginal: boolean): Address {
const result = this.recommendation;
if (!result || result.revision !== this.revision)
throw new Error("Validate the current address first.");
if (!useSuggestion && !allowOriginal)
throw new Error("This delivery requires a corrected address.");
const chosen = useSuggestion ? result.suggested : result.original;
this.entered = { ...chosen };
this.recommendation = null;
++this.revision;
return { ...chosen };
}
}
// Construct the suggested Address after mapping provider fields and preserving
// required company/suite data. Save only after the buyer chooses.If validation starts at revision 2 and the buyer edits the suite number, edit advances to revision 3. receive(2, suggestion) returns false, so an older provider response cannot replace the new input. For the current revision, choose(false, true) keeps the original address; choose(false, false) rejects that choice when the delivery policy requires a corrected address.
Persist once the choice is settled
Save only after the buyer's choice is settled. Carry the existing address ID through the flow when editing an address; otherwise a suggestion may create an unwanted second address-book entry. Decide explicitly whether a new address belongs in the address book or only to this checkout.
Recalculate shipping methods, rates, and tax from the saved destination. Keep billing and shipping recommendation state separate when the buyer uses different addresses. A valid form does not make a shipping quote for the previous destination valid.
Test the full checkout lifecycle
Use a fake validator that can return an exact match, a changed street, multiple candidates, no candidate, unsupported country, slow response, and failure. Test accepting the suggestion, keeping the original where allowed, canceling, editing again, and submitting twice.
Check that a late response cannot replace a newer address. Verify suite and company fields, country and region mappings, existing address IDs, and address-book duplication. Navigate the recommendation interface with a keyboard and confirm focus returns to a useful control. Finally verify that shipping and totals are recalculated from the accepted address rather than the last submitted form snapshot.
- Do not expose provider credentials to the browser.
- Keep address payloads out of routine diagnostic logs.
- Differentiate user validation errors from dependency failures.
Explain uncertainty without adding friction
Show the two addresses in a clear comparison and identify what changed. Avoid a generic 'corrected address' label when the provider has only offered a recommendation. The buyer may know a delivery detail that is absent from the external service.
A good integration assists the buyer while maintaining a coherent checkout state. The underlying service call is only one step. Preserved input, current-response checks, explicit choice, and correct recalculation are what turn that call into a reliable purchasing experience.
References and further reading
Independent guidance from GCG. Znode is a trademark of its owner. Examples use fictional data and are not official platform documentation. Suggest a correction.