Smarty¶

Smarty address verification with USPS DPV/RDI validation, vacancy detection, CMRA indicator, and rooftop geocoding. US and US-territory addresses are validated against the Smarty US Street Address API; all other countries fall back to the Smarty International Street API. Choose it when you want USPS-grade normalization plus delivery-point intelligence (is this address real, deliverable, vacant, a mail drop?) feeding checkout validation and order verification metadata.

What It Provides¶

• Address validation strategy — SmartyStrategy, registered with the strategy resolver as an AddressValidationStrategy implementation named smarty when the extension activates (strategy family address_validation).
• USPS-grade normalization — the validated address comes back with the USPS delivery lines, city/state, ZIP+4 (the plus-4 code is appended when Smarty returns one), and county name.
• DPV confirmation — the USPS Delivery Point Validation match code is surfaced on the result (Y confirmed, S secondary missing, D default match, N not confirmed). Y/S/D count as valid; Y maps to deliverable and N to undeliverable.
• RDI, vacancy, and CMRA — residential/commercial delivery indicator, USPS vacancy flag, and a Commercial Mail Receiving Agency (e.g. UPS Store) warning.
• Address type classification — po_box, government, or military from the USPS record type, otherwise residential/commercial from RDI.
• Rooftop geocoding — latitude/longitude from Smarty's metadata, stored on the order when checkout validation runs.
• International verification — non-US addresses go to the International Street API; Verified and Partially Verified statuses count as valid.
• Nothing else — the package contributes no webhook endpoints, Temporal workflows, schedules, admin pages, GraphQL fields, or event subscriptions.

Setup¶

1. Once installed (or dev-linked in development), the extension is discovered at startup; it can be enabled per channel from Settings > Extensions (per-channel activation via ChannelExtension).
2. Create a Smarty account and get the Auth-ID and Auth-Token from your account dashboard (the manifest's install hint: "Create a Smarty account and configure Auth-ID and Auth-Token").
3. Provide the credentials. The strategy factory reads auth_id / auth_token from a config dict when one is supplied and otherwise falls back to the SMARTY_AUTH_ID / SMARTY_AUTH_TOKEN environment variables — the strategy proxy registered at boot calls the factory with no config dict, so in the current code path the environment variables on the API service are what the validation call actually reads.
4. Select the provider for a channel by setting its Address Validation provider to smarty — from Settings > Channels (edit a channel; saved through the updateChannel mutation), or the Settings > Geocoding & Geolocation page (which drives the configureChannelGeocoding GraphQL mutation); both require the settings.edit permission.
5. Checkout address validation only runs when the channel's Geocoding Enabled toggle is on — the checkout mutation reads geocoding_enabled before validating the shipping/billing addresses.
6. Test with the validateAddress GraphQL query, or the address-validation test panel on the Settings > Geocoding & Geolocation page ("Validate a structured address against configured providers").

Configuration Reference¶

Operational Notes¶

• Fail-open when unconfigured. With no Auth-ID/Auth-Token the strategy returns the input address unmodified and marked valid. The core GeolocationService is also fail-open: if the provider raises, checkout validation is skipped rather than blocking the order.
• Country routing. US, PR, VI, GU, AS, and MP go to the US Street Address API (us-street.api.smarty.com/street-address); every other country goes to the International Street API (international-street.api.smarty.com/verify).
• Single-candidate matching. US requests are sent with match=invalid and candidates=1, so Smarty always returns at most one best candidate; an empty response yields a no_match error and undeliverable.
• Warnings raised — missing_secondary (DPV S: valid but missing apt/suite), default_match (DPV D: matched a default record), cmra (Commercial Mail Receiving Agency), and vacant (USPS vacancy flag). International misses raise no_intl_match (error) or intl_unverified (warning).
• Provider metadata on the result carries dpv_footnotes, cmra, record_type, county_fips, carrier_route, and precision for the US API, and verification_status / address_precision for the international API.
• Checkout capture. When the checkout mutation validates addresses, the result's address type, RDI, DPV match code, and vacancy flag are stored as verification metadata for fraud review and the order snapshot; a block validation mode on the channel rejects checkout on error-severity issues (default mode is warn_public).
• HTTP timeout is 10 seconds per API request.
• Alternative providers implementing the same strategy family: Google Maps Platform, Radar, and ShipStation Validate Address.