Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in

Collect customer addresses

Learn about collecting customer address information to calculate tax.

Stripe Tax requires your customer’s location to automatically calculate tax. This requirement applies even if you don’t have an active registration. This guide helps you understand how to collect addresses from your customers.

Checkout and Payment Links

Checkout handles the collection of customer addresses for you, including those created by Payment Links.

Invoicing, Subscriptions, and custom payment integrations

If you don’t use Payment Links or Checkout, you’re responsible for the collection of customer addresses.

Regional considerations
United States

In the United States, sales tax rules and rates vary by state, with some states having hundreds of districts setting their own rates. We recommend collecting a full address (including line1, city, and state) from your customers in the US.

Invoice finalization errors

Finalizing invoices with Stripe Tax requires a recognized customer location. Location details might be missing or invalid if you update or remove a customer’s default payment method, or if you didn’t provide tax[validate_location]="immediately" when creating or updating a customer.

If we don’t have a recognized customer location, invoices for a subscription continue to finalize automatically but without calculating taxes. This has the following effects:

  • The automatic_tax[enabled] parameter changes to false on the subscription and invoice.
  • The Invoice[automatic_tax][disabled_reason] parameter changes to finalization_requires_location_inputs.
  • The Subscription[automatic_tax][disabled_reason] parameter changes to requires_location_inputs.
  • If the subscription has a schedule, we set automatic_tax[enabled] to false on the current phase and in default_settings. We set the disabled_reason in both to requires_location_inputs.
  • We send invoice.updated and customer.subscription.updated events to inform your integration of these changes.
    • If there’s a schedule, we also send a subscription_schedule.updated webhook.
  • The invoice finalizes without calculating or collecting taxes. It won’t contain any tax amounts.
  • We collect payment as usual according to the collection method for the invoice.

To review subscriptions without automatic tax calculations in your Stripe Dashboard, visit your Subscriptions page and filter the view by the Automatic tax not enabled option. To reactivate automatic tax for these subscriptions in the future, make sure you have at least one valid customer location, and activate automatic tax through the Stripe Tax Dashboard.

Exceptions to automatically disabling tax

Stripe returns an error and leaves the invoice in a draft status when finalizing with the API or Dashboard without a valid customer location. In the API, this returns an HTTP 400 error with a code of customer_tax_location_invalid.

Similarly, for automatic finalization of standalone invoices without a subscription, the invoice remains a draft if the customer location isn’t valid. We send an invoice.finalization_failed event with the invoice last_finalization_error[code] being customer_tax_location_invalid.

How you recover from a customer_tax_location_invalid error depends on whether you have or can collect a customer address.

OptionalWhich customer address we use

Stripe Tax uses a single address as your customer’s location when calculating tax. How we choose an address doesn’t depend on the type of product you sell.

You can see which location was used for an automatic tax calculated payment in the Automatic tax calculation section of the Transactions details page in your Dashboard. You can also review the Customer API object tax parameter to see the tax-location-source.

Checkout and Payment Links

Checkout and Payment Links use the address collected during the session.

Invoicing, Subscriptions, and custom payment integrations

We use the first viable item in the list below to determine your customer’s location:

  1. We use your customer’s shipping address, if present.
    • If a shipping address is present but invalid, we raise a customer_tax_location_invalid error instead of trying the next address in this list.
  2. We use your customer’s billing address, if present.
    • If a billing address is present but invalid, we raise a customer_tax_location_invalid error instead of trying the next address in the list.
  3. We use the billing details of the most specific payment method, if present.
    1. Default payment method of the invoice, if present.
    2. Default payment method of the subscription, if present.
    3. Default payment method of the customer, if present.
  4. We use your customer’s IP address, if present.

Note

If the billing details associated with a payment method are incomplete or missing, we try assembling a more complete billing address. For example, knowing the country of the card issuer, we combine it with the postal code in the billing details.

Tax API

For the Tax API, the address hierarchy follows a simplified approach:

  • The address provided in the API request is used directly for tax calculations.
  • There is no fallback to other address sources such as shipping address, billing address, payment method, or IP addresses.

Warning

When using the Tax API, you must provide a valid and complete address in your API requests, or they return an error. Include the country and, where applicable, the postal code and state.

OptionalMinimal address collection

Each billing and shipping address has the fields line1, line2, city, state, postal_code, and country. The country must be a two-letter ISO 3166-1 code.

Example addresses ExplanationSupported
  • line1: 27 Fredrick Ave
  • city: Brothers
  • state: OR
  • postal_code: 97712
  • country: US

Full address

A full address includes at least a line1 (street address or PO Box), city, state, postal code, and country.

The address is matched to the closest address or street in the US Postal Service address database. If a match isn’t found, we use the geographical center (average location of addresses) of the 5-digit postal code as a fallback.

9-digit postal code:

  • postal_code: 97712-4918
  • country: US

5-digit postal code:

  • postal_code: 97712
  • country: US

Country and postal code

If you provide a 5-digit or 9-digit postal code, our system only uses the initial 5 digits for tax calculations. The tax is calculated at the geographical center, which reflects the average location of addresses within the 5-digit postal code area. Check that this is suitable for your business.

  • state: OR
  • country: US

Country and state

We can’t calculate tax for US customers with only an ISO country code and state code.

  • country: US

Country

We can’t calculate tax for US customers with only an ISO country code.

Use one of the supported address formats above to make sure that we can recognize your customer addresses consistently.

OptionalRegional considerations

United States

IP Address Accuracy

In most cases, we can resolve an IP address to a physical area, but its precision varies and might not reflect the customer’s actual location. Given that the US imposes local taxes, we don’t recommend relying on a customer’s IP address to determine their address.

Precise Address Lookup

Stripe Tax supports full rooftop-accurate address lookup for customer addresses in the US, meaning you can attribute your customer’s location to a specific house or building. This provides greater accuracy in the US, where two houses located side-by-side on the same street might be subject to different tax rates, due to complex jurisdiction boundaries.

For addresses outside the US, Stripe uses the country, state, and postal code fields to determine tax obligations without comparing against a comprehensive address database. See “Special jurisdictions and excluded territories” for more about when the state and postal code are used.

Note

Stripe Tax uses the 5-digit US postal code if the address lacks sufficient information, has inconsistencies, or otherwise can’t be matched to an address in the US Postal Service address database.

US Military and Diplomatic Addresses

Stripe Tax calculates no tax for US military and diplomatic mail going overseas. Overseas military and diplomatic addresses are assigned an APO, FPO, or DPO zip code, and the USPS treats it as domestic mail before transferring it to the military. Because sales to these special zip codes are sent out of the country, their sales taxes don’t apply.

ZIP Codes

In the United States, Stripe Tax supports calculating sales tax with only a basic 5-digit US postal code. We use the point at the geographical center of the 5-digit postal code area as your customer’s location. The tax rate at this point might differ from the tax rate at your customer’s full address. Whether or not a postal code alone is sufficient to identify the correct tax rates to impose varies by state.

We recommend against relying on a postal code alone in the following states:

  • Alabama
  • Alaska
  • Arizona
  • Arkansas
  • California
  • Colorado
  • Illinois
  • Kansas
  • Louisiana
  • Missouri
  • Nebraska
  • New Mexico
  • North Dakota
  • Oklahoma
  • South Dakota
  • Texas
  • Utah
  • Washington
  • West Virginia

Note

Stripe Tax also supports 9-digit ZIP+4 codes, but we don’t use the four additional digits.

Europe

IP Address Reliability

In regions that don’t impose local taxes, such as the EU, an IP address is more likely to resolve to an accurate address.

Excluded territories

In Europe, tax authorities in each country impose tax, not state or local authorities. The tax rate for the country doesn’t apply in a small number of areas, even though they’re physically located in a country that imposes tax. For example, the Italian postal code “00120” identifies Vatican City, where Italian VAT doesn’t apply.

Collect your customer’s postal code or state to enable Stripe Tax to determine when your customer is located in an excluded territory.

See the list of excluded territories supported by Stripe Tax.

See also

Was this page helpful?
YesNo