USPS Address Validation in Znode

Overview

USPS Address Validation enables organizations to validate customer-entered shipping and billing addresses in real time using the United States Postal Service (USPS). This improves delivery accuracy, reduces failed shipments, and enhances the checkout experience.

The feature is available as a configurable plugin in the Admin Console and can be managed at the store level.

Prerequisites

Before configuring USPS Address Validation, ensure the following:

The USPS Address Validation plugin is installed and active

Valid USPS API credentials are available:
- Client ID
- Client Secret
- Required service endpoints are available:
- Access Token URL
- Recommended Address URL

Administrator access to System Settings and Store configuration

Key Capabilities

Real-time address validation during checkout and address entry

Store-level enablement and configuration

Configurable customer experience (allow or restrict overrides)

Validation applied to checkout and address book

Graceful fallback if USPS service is unavailable

Configure the USPS Plugin

Steps
- Navigate to Admin Console.
- Go to System Settings > Plugins > Installed Plugins.
- Locate and select the USPS plugin.
- Enter the required configuration values:
- Access Token URL
- Recommended Address URL
- Ensure the plugin is set to Active.
- Select Save.

Expected Outcome
- The plugin is configured successfully and ready for use.
- The system prevents saving if required fields are missing.

Create a Configuration Set

Configuration Sets define reusable USPS validation configurations that can be assigned to stores.

Steps
- Navigate to System Settings > Plugins > USPS > Configuration Sets.
- Select Add New. Enter the required fields:
  - Configuration Code – Enter a unique identifier
  - Display Name – Enter a user-friendly name
  - Client ID – Enter the USPS client ID
  - Client Secret – Enter the USPS client secret
  - (Optional) Review additional settings such as Shipping Calculation Method if applicable. (Set to Total Cart Weight by default with an option to Per-Item Shipping)
  - Is address validation configuration set – Set to NO by default (Setting it to yes allows this configuration set to be available for selection under the Configuration set drop down under the address validation setting in the additional attribute section of the manage store screen)
  - Select Save & Close.

Expected Outcome
- The configuration set is created successfully.
- The configuration becomes available for assignment to stores.

Enable Address Validation for a Store

Steps
- Navigate to Store Settings.
- Open the required store.
- Locate the Address Validation Settings section.
- Set Enable Address Validation to Yes.
- Select a Configuration Set from the dropdown.
- (Optional) Configure additional settings:
  - Validate Addresses in Address Book Page
  - Allow User to Override Address
- Select Save.

Expected Outcome
- Address validation is enabled for the store.
- Validation applies during checkout and address management.

Address Validation on Storefront

When Validation Occurs

The system validates addresses when a customer:

Enters shipping or billing details during checkout

Adds a new address

Edits an existing address

Address Scope

Only United States addresses are validated

Non-U.S. addresses are saved without validation

Validation Scenarios

Valid Address (No Changes)
- Address is accepted and saved automatically

Valid Address with Recommendation
- A standardized version is suggested
- Customer selects which address to use

Invalid Address with Recommendation
- A comparison screen is displayed
- Customer selects:
  - Original address (if allowed)
  - USPS recommended address

Invalid Address without Recommendation
- An error message is displayed
- Customer must retry or correct the address

Address Override Behavior

Override Enabled
- Customers can proceed with their original address

Override Disabled
- Only USPS recommended address can be used
- Original address option is hidden

Failure Handling

If the USPS service is unavailable:

Checkout is not interrupted

Address is saved using default behavior

No technical errors are displayed to the customer

Important Notes

Address validation is disabled by default

Only one configuration set can be assigned per store

Changes take effect immediately after saving

Existing addresses are not modified

Validation applies only during checkout or address entry