Understand add and edit address states
The address form can collect delivery details, show configured location tools, and start an add or edit request. A completed-looking form or a changed screen does not by itself prove that the saved address, default address, active order location, or cart delivery context all changed.
:::warning Important limits Treat a save as unresolved until the app returns a current, authorized state for the intended account or guest journey. Do not repeat a save merely because another screen opened, a marker moved, or a loading indicator disappeared. :::
Add and edit are different targets
Add starts a new address candidate. Edit starts from an existing saved address candidate. The visible fields can look alike, but edit also needs a current, owner-authorized target.
Information passed by the previous screen can influence whether the form looks like add or edit and where it tries to return. That route context is a navigation hint. It is not proof that the address, account, guest session, project, checkout, or cart is current or authorized.
Fields and validation
The form can include an address line, internal or unit information, postal information, delivery notes, and a tag. Which fields are visible or required can depend on the current project configuration and validation state.
Validation only describes whether the current candidate satisfies the form rules. It does not prove ownership, delivery coverage, provider success, or server settlement. A duplicate-looking candidate can also be rejected before a save is attempted.
Typed and precise location are separate
Typing an address creates a text candidate. Choosing a suggestion, using device location, or moving a map pin can add a more precise location candidate. These states must remain distinguishable:
| Visible state | What it can mean | What it does not prove |
|---|---|---|
| Typed text | A local address candidate exists | A provider resolved it or it can receive delivery |
| Suggestions | A configured provider returned candidates | A candidate is authorized, current, or serviceable |
| Map or pin | The form has a location candidate to present | The location was saved or made active |
| Device-location result | The operating system and location path returned a candidate | Permission remains granted or the address is correct |
| Manual details | Additional delivery context was entered | The saved record or cart now contains it |
Location permission and provider availability are separate from saved-address authority. If precise location is unavailable, use only an offered manual or saved-address alternative; do not infer coordinates from a marker or retry a provider action repeatedly.
Address identities must stay separate
The same address text can appear in several independently settling layers:
| Layer | Owner or authority | Safe interpretation |
|---|---|---|
| Form candidate | Current form generation | Unsaved local input |
| Saved address | Current account or authorized guest transfer | A persisted record only after an authoritative response |
| Saved default | Address owner and default-address transaction | The preferred saved record; not necessarily the active order location |
| Active order location | Current ordering context | The location used for current discovery or ordering decisions |
| Cart delivery context | Current cart and checkout authority | The delivery data considered by checkout |
Matching text or a selected-looking control does not make these layers equivalent.
Saving can have several stages
A save can involve more than the address record. Depending on the journey, the app can also try to select the new address, refresh account information, update order options, reconcile a cart, or return to another screen.
Those stages can settle separately. For example, the address record might be accepted while its default or active-order state is still unknown, or navigation might occur before a later stage finishes. When layers disagree, keep the outcome unresolved until current authorized reads reconcile them.
Guest, account, and checkout boundaries
A guest address candidate must not silently become an address for a different signed-in account. Guest creation, later account conversion, saved-address ownership, checkout delivery details, and cart transfer are separate responsibilities.
On account, project, session, or checkout changes, discard stale form and provider results. Re-enter from the current journey and confirm which address layer the screen is showing before taking another deliberate action.
Partial and unknown outcomes
Use these state classes when supportable:
- Not started: no save intent was submitted.
- Pending: the current save generation has not returned a final result.
- Rejected: the current stage returned a validation, authorization, conflict, or availability failure.
- Partial: one layer changed while another did not return a reconciled state.
- Unknown: the app cannot determine whether a write settled, such as after interruption or a lost response.
- Reconciled: current authorized state identifies the saved record and any relevant default, order, and cart layers.
Do not report success from a toast, marker, closed form, or destination alone.
Troubleshooting by observed state
| Observed state | Safe next step | Owning boundary |
|---|---|---|
| Required field remains invalid | Review only the visible field guidance | Form validation/configuration |
| Typed text has no suggestion | Use an offered manual or saved alternative | Suggestion provider and form |
| Device location is unavailable | Review the location-permission guide; do not repeatedly request it | Operating system permission/location |
| Marker and text disagree | Treat location as unresolved and avoid saving until the form is consistent | Map/provider and form generation |
| Save remains pending | Wait; do not repeat the write | Address API and current request generation |
| Form closes but address is absent | Reopen the current authorized address state; do not assume failure or retry | Saved-address reconciliation |
| Address is saved but not active | Keep saved, default, order, and cart states separate | Order options/cart owners |
| State changed after account or project switch | Leave the stale flow and re-enter from the current context | Session/project lifecycle |
Support reports should use only a value-free state class such as “address save unresolved.” Do not include address text, location details, contact information, account or cart identifiers, provider data, or private screenshots.
Privacy and accessibility
Share only the minimum address and location information required for the chosen action. Do not copy precise location, provider responses, or saved delivery details into support notes.
Field labels, required and error states, map alternatives, loading state, save availability, and result announcements must remain understandable without relying on color, a pin position, or a toast alone. Large text, keyboard behavior, focus order, screen-reader names, error association, and focus return require current-platform verification before any accessibility claim.
Recertification triggers
Recheck this reference when address fields or validation change; a map, suggestion, geocoding, or location-permission integration changes; add/edit callers or route parameters change; guest creation or account conversion changes; saved-default, order-option, cart, or checkout reconciliation changes; request cancellation or retry behavior changes; account, project, or session teardown changes; or shared form and accessibility primitives change.
Related guides: Choose a delivery location · Location permission and unavailable-location states · Understand map states · Choose order type and time · Manage saved addresses · Customer and delivery details