Shipping Address Validation
Last Updated: June 22, 2026
This guide covers address validation in the storefront checkout: how UltraCart verifies the shipping address a customer enters, offers a corrected version, and handles addresses it can't confirm. It also walks through the checkout elements and settings that drive the experience in the Storefront Visual Builder (SFVB).
Table of Contents
Overview
Address validation checks the address a customer enters at checkout against an authoritative address database. If the address is deliverable, checkout continues. If a cleaner, standardized version exists, the customer can accept it. If the address can't be confirmed, you decide whether to ask for a phone number and let the order through, or to block it until a valid address is entered.
The benefit is fewer failed deliveries, fewer address-correction charges from carriers, and cleaner data flowing into fulfillment.
In the storefront, address validation is built into the CheckoutForm element. It is driven by a small set of CheckoutForm settings plus two modals: a suggestion modal ("Did you mean the suggested address?") and a confirm modal ("Confirm Shipping Address"). Standard storefront themes ship with these elements already in place, so for most merchants this is a configuration task rather than a build-from-scratch task.
Important: Shipping address validation requires an active Smarty Streets integration. Smarty is the service that actually verifies addresses. Connect and enable it first; without it, none of the prompts described here will appear.
Requirements
-
A connected and enabled Smarty Streets integration, with Verify the shipping address at checkout turned on.
-
A storefront checkout built on a theme that includes the Address Validation elements (the standard themes do).
-
StoreFront editor access to the Storefront Visual Builder if you need to adjust or re-add the elements.
-
A checkout theme at the minimum version listed under Theme Compatibility.
Theme Compatibility
Address validation ships in the latest checkout theme updates and works in both single-page and multipage checkout. The feature is available starting at the minimum theme version below. If your storefront is on an older version, update the theme before configuring address validation.
| Theme | Minimum version |
|---|---|
| Elements | 2.22 |
| Hero | 1.25 |
| Jewel | 1.21 |
| Lifty | 1.25 |
| Setting | What it does |
|---|---|
| Validate Address Type | Which address to validate. Most merchants leave this at shipping. |
| Validate Address Selection Element | The element that contains the address validation suggestion UI (the "Did you mean…?" picker). Defaults to the storefront's checkoutaddressvalidationsuggestion element. |
| Setting | Purpose |
|---|
| Setting | Purpose |
|---|---|
| Validate Address Type | Which address to validate (usually shipping). |
| Validate Address Selection Element | Element rendering the suggestion picker. |
| Validate Address Selection Show These | Modal containing the suggestion element. |
| Validate Address Confirm Element | Element rendering the confirm/block UI. |
| Validate Address Confirm Show These | Modal containing the confirm element. |
Verification
To confirm address validation is working end to end:
-
In Smarty settings, confirm the integration is enabled and Verify the shipping address at checkout is on. See Smarty Streets Integration.
-
Place a test order and enter an address with a deliberate, correctable error (for example, a misspelled street suffix or a missing ZIP+4). Expect the Suggestion Modal to offer a corrected version.
-
Enter an address that can't be verified (for example, a non-existent street number). Expect the Confirm Modal — either the phone-number prompt or the block message, depending on your setting.
-
Enter a clean, deliverable address and confirm checkout proceeds with no prompt.
Troubleshooting
No validation prompts appear at checkout
Symptoms: Customers are never asked to confirm or correct an address.
Cause: Smarty isn't connected/enabled, or the CheckoutForm isn't pointed at the validation elements.
Solution:
-
Confirm the Smarty Streets integration is enabled and Verify the shipping address at checkout is on.
-
In the CheckoutForm settings, confirm the four "Selection/Confirm Element" and "Show These" fields are populated.
-
Confirm the Suggestion and Confirm modals exist in the checkout hierarchy.
The suggestion element shows a placeholder note in the editor
Symptoms: Inside the SFVB, the suggestion element displays a message about needing to be enclosed in a checkout condition.
Cause: The element only renders when the customer has an address selected; outside that flow it shows guidance text.
Solution: This is expected in the editor. As long as the element is inside the IS ADDRESS VALIDATION ENABLED condition (it is in standard themes), live checkout behaves correctly.
Customers are blocked when you expected them to continue (or vice versa)
Symptoms: Unverifiable addresses are blocked when you wanted a phone-number fallback, or allowed through when you wanted them blocked.
Cause: The When the customer will not provide a verified address setting drives which Confirm Modal behavior is active.
Solution: In Configuration → Checkout → Shipping → Checkout Options, set When the customer will not provide a verified address to Allow the order through, Require a phone number, or Block the order as desired, and save.
Related Documentation
-
Smarty Streets Integration — required; the service that performs address verification
-
Smarty signup — create a Smarty account