Validate order address
Use this endpoint to validate a physical shipping address before placing an order. Use this when end users are entering shipping addresses in your platform UI - validating up front catches errors early and reduces fulfillment failures. This endpoint is only relevant for physical variants (variants where shippingRequired is true); digital variants (e.g. gift cards) require only countryCode and skip address validation.
Required fields:
address- the address object to validate. Contains:address1- street address (validated as required)address2- apartment, suite, floor (optional)city- city name (validated as required)provinceCode- state or province code (1-3 uppercase alphanumeric characters)postalCode- postal/ZIP code (alphanumeric, 3-10 characters)countryCode- two-letter uppercase country code
Optional parameters:
Request-Sourceheader - source of the request (api_native, api_zapier, api_salesforce, api_ftp, api_make)
Please note:
- Successful validation returns one of two
resultvalues:verified- the address is correct and deliverableambiguous- the address was found but with ambiguity (e.g. multiple matches). Consider surfacing the response message to the end user to confirm before proceeding.
- Returns
400with a per-field errors array when address validation fails (e.g. invalid address format, missing required fields). Each entry includes the offending path, a human-readable message, and the errorCode. - Returns
422when the address is well-formed but cannot be found by the validation service. - This endpoint does not place an order - it’s a pre-flight check. Always follow up with placing an order once validation succeeds.
- Do not call this endpoint for digital orders. Digital variants (
shippingRequired: false) don’t have a physical shipping address to validate -countryCodealone is sufficient at order placement.
Permissions
- Requires:
orders:read:maskedororders:read:unmasked
Authorizations
Company Level Authentication
Include your API key in the X-Api-Key header for every request:
Headers
Optional account identifier for swag validation/filtering.
"acc123456"
Optional company identifier for swag validation/filtering.
"cmp123456"
Body
Validate order address request body.
Physical shipping address for order delivery.
Response
Address validation result.
Address validation response.
Address validation result.