Skip to main content

​
Overview

Different countries have different address formats and requirements. The address requirements endpoint lets you look up the minimum address fields needed for a given country before submitting addresses for tax calculations or transactions. Use this endpoint to:
  • Validate addresses client-side before calling /calculate or /transactions, reducing failed requests.
  • Build dynamic address forms that adapt to each country’s requirements.
  • Check postal code formats using the provided regex pattern.
  • Restrict state/province inputs to valid codes for the country.

​
Field requirement levels

Each address field returns one of three requirement levels:

​
How address requirements are used

The /calculate and /transactions endpoints only require country at the schema level for all addresses. All other field requirements — including postal_code and state — are determined per-country using the rules returned by this endpoint. If a field marked as REQUIRED for a country is missing or incorrectly formatted, the API returns a 400 error with details about the validation failure. Querying address requirements ahead of time lets you catch these issues before submitting a request.

​
Regional differences

Address requirements vary by country and region. Here are some key differences to be aware of:
  • United States (US): address_line_1, city, state, and postal_code are all REQUIRED. State codes must be valid 2-letter US state abbreviations (e.g., CA, NY).
  • EU countries (e.g., DE, FR): address_line_1, city, and postal_code are REQUIRED, while state is OPTIONAL. Postal codes are validated against the country’s regex pattern.
  • United Kingdom (GB): address_line_1, city, and postal_code are REQUIRED, while state is OPTIONAL. Postal codes must match the UK format (e.g., SW1A 1AA).
  • Canada (CA): address_line_1 and city are REQUIRED. state and postal_code requirements follow Canadian postal standards. When provided, state codes must be valid 2-letter province/territory abbreviations (e.g., ON, BC).
Even when a field is OPTIONAL, providing it improves tax calculation accuracy. For example, including a state code for EU or GB addresses helps resolve the correct tax jurisdiction.

​
Postal code validation

When postal_code_regex is present in the response, you can use it to validate postal codes before submission. For example, the US pattern ^\d{5}(-\d{4})?$ accepts both 5-digit and 9-digit ZIP codes.
The postal_code field is required for the US, EU countries (such as DE and FR), and GB. For CA, postal_code is optional. When a postal code is provided, it is validated against the country’s regex pattern.

​
Valid state codes

For countries with defined state or province subdivisions (e.g., US, CA), the valid_state_codes array lists all accepted codes. Use this to populate dropdowns or validate state input in your address forms.