Skip to main content

Validate Address

POST 
/api/portal/addresses/validate

Checks a typed address without saving it — use it before placing an order to an address that is not in the address book, such as a dropship order's consumer address.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Body (every field optional, so a partly entered address can be checked)

  • name, company, address1, address2, address3, city, province, country (strings, max 255)
  • province_code (max 16), zip (max 32), country_code (max 5; USA is read as US), phone (max 64), email (max 255)
  • shipping_method_id (integer) — the intended shipping method, so the PO Box warning can name its carrier.

Response

  • missing — the first required part that is blank (missing a recipient name, missing a street address, missing a city, missing a state, missing a ZIP code, missing a country), or null. This is the only result that blocks an order. missing_field is the field it is about (name, address1, city, province_code, zip, country_code).
  • warnings — problems that do not block an order, each with a stable code, the field it is about and a message: postal_format (the postal code does not match the country's format — checked for US, CA, AU, NZ, GB, DE, FR, MX), unknown_state (not a US state/territory or Canadian province), po_box (the carrier cannot deliver to a PO Box; USPS can), phone_required (an international address with no phone number).
  • valid — true only when nothing is missing and there are no warnings.
  • suggestion — reserved for a corrected address from an address-verification provider; currently always null.

A US state typed as a name ("Oregon") is read as its code. Returns 422 only when a field has the wrong type or is too long. Viewers get 403 viewer_read_only. Rate limited to 60 requests/minute.

Request​

Responses​

OK

Response Headers
    Content-Type