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:
LevelMeaning
REQUIREDThe field must be provided. Omitting it may cause tax calculation errors.
OPTIONALThe field is accepted but not mandatory. Providing it improves accuracy.
IGNOREDThe field is not used for this country and can be omitted.

​
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.