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).

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

Theme	Minimum version
Elements	2.22
Hero	1.25
Jewel	1.21
Lifty	1.25
Native	1.19
Natural VB	1.19
Poppy	1.12

Check your storefront's current theme version under its StoreFront theme settings. If you're below the minimum, apply the latest theme update so the Address Validation elements and conditions are present.

How It Works

When a customer submits their shipping address, the checkout sends it to Smarty for verification and reacts to the result:

The two modals correspond to two outcomes:

The Suggestion Modal appears when Smarty has a deliverable, standardized version of the address that differs from what the customer typed. It lets the customer pick between what they entered and the suggestion.
The Confirm Modal appears when Smarty cannot verify the address and the When the customer will not provide a verified address setting is set to Require a phone number or Block the order. If that setting is Allow the order through, no Confirm Modal is shown and the order simply proceeds. (The CheckoutForm condition that wraps this modal is named IS ADDRESS VALIDATION PHONE OR BLOCK for exactly this reason.)

In the SFVB hierarchy, the modals live inside checkout conditions on the CheckoutForm so they only render when relevant:

CHECKOUTFORM
├─ IS ADDRESS VALIDATION ENABLED            (checkout condition)
│  └─ ADDRESS VALIDATION SUGGESTION MODAL
│     ├─ HEADLINE - DID YOU MEAN
│     └─ CHECKOUTADDRESSVALIDATIONSUGGESTION
└─ IS ADDRESS VALIDATION PHONE OR BLOCK      (checkout condition)
   └─ ADDRESS VALIDATION CONFIRM MODAL
      ├─ HEADLINE - EMAIL
      └─ CHECKOUTADDRESSVALIDATIONCONFIRM
         ├─ ALLOW PHONE TO UNVERIFIED ADDRESS  (checkout condition)
         └─ BLOCK UNVERIFIED ADDRESS           (checkout condition)

The CheckoutForm Address Validation Settings

Select the CheckoutForm element and open its settings. Scroll to the Address Validation section. These settings tell the checkout which element renders the validation UI and which modal contains it.

Setting	What it does

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.
Validate Address Selection Show These	The modal that contains the suggestion element. UltraCart opens this modal when a suggested address is available.
Validate Address Confirm Element	The element where the customer confirms an unverified address (provides a phone number or is blocked). Defaults to the `checkoutaddressvalidationconfirm` element.
Validate Address Confirm Show These	The modal that contains the confirm element. UltraCart opens this modal when an address can't be verified.

"Show These" fields reference a modal by its element ID. In standard themes these are pre-wired to the Suggestion Modal and Confirm Modal that ship with the checkout, so you usually don't need to change them.

The Suggestion Modal

The Address Validation Suggestion Modal is shown when Smarty returns a standardized address that differs from what the customer typed.

It contains:

A headline ("Did you mean the suggested address?").
The checkoutaddressvalidationsuggestion element, which renders the side-by-side choice between You entered and We suggest.
A Yes, save and continue action that accepts the highlighted address and proceeds.
A No, try a different address action that returns the customer to the address form.

The suggestion element only renders once the customer has an address selected. If you open it in the SFVB editor outside that flow, you'll see a placeholder note explaining that it should be enclosed in a checkout condition (which it is, via IS ADDRESS VALIDATION ENABLED). That's expected in the editor and does not indicate a problem.

The Confirm Modal

The Address Validation Confirm Modal is shown when Smarty cannot verify the address — but only when your Smarty When the customer will not provide a verified address setting is Require a phone number or Block the order. (With Allow the order through, the modal is skipped and the order proceeds.) Its content adapts to that setting using two checkout conditions inside the checkoutaddressvalidationconfirm element.

Require a phone number

When the setting is Require a phone number, the ALLOW PHONE TO UNVERIFIED ADDRESS condition is active. The customer is told the address couldn't be verified, is asked for a required phone number, and can then proceed.

The modal shows:

An explanation that the address couldn't be verified, with a prompt to click Save and Continue if they're confident it's correct.
A required Phone Number field, with a note that it's only used if you need to contact them about the order.
A Save & continue action.

Block the order

When the setting is Block the order, the BLOCK UNVERIFIED ADDRESS condition is active instead. The customer cannot proceed with the unverified address.

The modal shows the message "This address can't be used. Please enter a different address." and a Try a different address action that returns them to the address form.

Both behaviors live in the same Confirm Modal. The Smarty setting decides which one the customer sees; you do not need to build two separate modals.

Settings Reference

The behavior of validation is controlled in two places.

Smarty integration (Configuration → Checkout → Shipping → Checkout Options):

Setting	Purpose

Setting	Purpose
Verify the shipping address at checkout	Turns validation on.
Offer the corrected address as a suggestion	Enables the Suggestion Modal flow.
When the customer will not provide a verified address	Chooses the fallback for an unverifiable address: Allow the order through (no Confirm Modal), Require a phone number, or Block the order.

See the Smarty Streets Integration guide for full details on these.

CheckoutForm element (Storefront Visual Builder):

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.