Developers & API
Address verification API
A standalone API for verifying, batch-verifying, and parsing addresses, with metered billing and a generous free tier.
Three endpoints
POST /api/v1/addresses/verify— verify a single address. Returns the canonical, USPS-corrected version plus a confidence score (high/medium/low/failed).POST /api/v1/addresses/verify-batch— verify up to 1,000 addresses in one call. Returns an array of results in the same order as the input.POST /api/v1/addresses/parse— take a freeform address string ("123 Main St Apt 4 NYC NY") and split it into structured fields (street1, street2, city, state, postal_code).
Authentication
API calls require a Bearer token in the
Authorization header. Generate a token at Admin → Settings → API Keys. The token must have the addresses:verify scope. Tokens scoped only to other resources (orders, shipments) will get a 403.Metered billing
Pricing:
- Free tier: 100 verifications per month across all endpoints. No cost.
- Verify: $0.01 per call beyond the free tier.
- Batch verify: Same per-address pricing; a batch of 200 = 200 verifications counted.
- Parse: $0.005 per call.
24-hour cache
Every verified address is cached for 24 hours keyed on the normalized input string. If you verify the same address twice in 24 hours, the second call is served from cache, returns instantly, and isn't billed. This dramatically reduces cost for workloads with repeated addresses (e.g. checkout abandonment recovery where you might verify the same address 3+ times).
Response format
A verification response includes: the original input, the corrected output (street1, street2, city, state, postal_code, country), a confidence enum, a list of changes made (e.g. "expanded `St` to `Street`"), and a deliverability flag. Use the confidence enum to gate whether you want to allow the order through automatically—most users block "failed" and prompt the customer to confirm "low."
FAQs
Which countries are supported?
US addresses use USPS verification. International addresses use a global verification provider with coverage in 240+ countries, but accuracy varies by region (US, UK, Canada, AU are best).
Is there a rate limit?
Yes—1,000 requests per minute per API key. Batch verify counts as 1 request regardless of batch size, so use batch for high throughput.
What happens to my data?
Addresses are processed in transit and cached for 24 hours as described. We don't store address data beyond the cache window for the standalone verification API.
How is the verification API different from order address validation?
It's the same underlying engine. The standalone API gives you direct access without creating an order—useful for checkout-time validation, list cleaning, or any non-shipping use case.