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 automatically validate addresses against these country-specific requirements. If a required field 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 and city are REQUIRED, while state and postal_code are OPTIONAL. When a postal code is provided, it is still validated against the country’s regex pattern.
  • United Kingdom (GB): address_line_1 and city are REQUIRED, while state and postal_code are OPTIONAL. Provided 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 postal 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. If a postal code is OPTIONAL for a country, you can omit it without error. However, if you provide a postal code, it must still match the country’s regex pattern — otherwise the API returns a 400 validation error.

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