Collect customer addresses

Stripe Tax requires your customer’s location to automatically calculate tax. This requirement applies even if you don’t register to collect taxes. This guide helps you decide what address information to collect from your customer and how to handle regional differences.

Supported address formats

Each billing and shipping address has the fields line1, line2, city, state, postal_code, and country. The tables below describe the address formats supported when calculating tax.

Use one of the above address formats to ensure that we can consistently recognize your customer addresses. The country field must always be a valid ISO country code.

Which customer address is used

Stripe Tax uses a single address as your customer’s location when calculating tax. We choose the same address whether you’re selling a digital product, a service, or a shipped good.

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

• We use your customer’s shipping address if it’s non-empty. Using an address that isn’t precise enough to calculate tax returns a status of requires_location_inputs.
• We use your customer’s billing address if it’s non-empty. Using an address that isn’t precise enough to calculate tax returns a status of requires_location_inputs.
• If the transaction is tied to a payment method with full billing details we use that billing address.
• If the billing details associated with the payment method are incomplete or missing, we assemble a billing address using the information provided, combined with details of the payment method itself (for example, using the country code of the credit card issuer to determine the country if the customer doesn’t provide it).
• Otherwise, we geolocate the Customer IP address and use that location as your customer’s location. We store this geolocation result and reuse it for future transactions involving the same customer.

The payment method tied to the transaction is the first one that’s set in this list:

• The Invoice default payment method
• The Subscription default payment method
• The Customer default payment method

Handling unrecognized locations

Invoice finalization fails and payment isn’t attempted for invoices with automatic_tax[enabled]=true if the customer location is unrecognized. When finalization happens during an API request, such as creating a subscription or sending an invoice, Stripe returns a customer_tax_location_invalid error. When finalization happens asynchronously, for example when a subscription renews, Stripe sends an invoice.finalization_failed webhook and the invoice remains in the draft state.

Finalizing invoices with finalization failures

How you correct customer_tax_location_invalid errors depends on whether you collect a recognized customer location. If you do, keep Stripe Tax enabled. If you don’t, disable Stripe Tax for the affected invoices and subscriptions.

To collect a recognized customer location:

1. Update the address of the affected customer. Provide enough location details for your customer. For example, a country and state code alone aren’t enough to calculate tax in the US.
2. Confirm that the customer location is recognized by ensuring the value of customer.tax.automatic_tax is supported or not_collecting.
3. Finalize the affected invoice.

Alternatively, to progress without a recognized customer location:

1. Update the affected invoice so automatic_tax[enabled]=false.
2. Update the affected subscription so automatic_tax[enabled]=false.
3. Finalize the affected invoice.

Detecting asynchronous invoice finalization failures

When an invoice can’t be finalized due to an unrecognized customer location, Stripe sends an invoice.finalization_failed webhook with automatic_tax[status] = 'requires_location_inputs'. When using subscriptions, we recommend listening for subscription and invoice related events because most activity happens asynchronously.

Preventing invoice finalization failures

To prevent invoices failing finalization due to an unrecognized customer location:

• Before updating an existing subscription from automatic_tax[enabled]=false to automatic_tax[enabled]=true, verify that the customer has a recognized location. If the customer’s location is unrecognized, update and verify it before enabling Stripe Tax on the subscription.
• After updating a customer that has a subscription with automatic_tax[enabled]=true, verify that the value of customer.tax.automatic_tax is supported or not_collecting.

Region-specific considerations

The complexity of taxes vary widely by region. Most countries have a single set of tax rules for the entire country. In the United States, sales tax rules and rates vary by state, with some states having hundreds of districts setting their own rates. In Canada, the type of tax and tax rate vary by province.

United States (US)

Postal codes

Stripe Tax supports calculating sales tax with only a basic 5-digit US postal code. The country field must be the ISO country code “US”. We use the point at the middle of the postal code area (or “centroid”) as your customer’s location. The tax rate at this point may differ from the tax rate at your customer’s full address. Whether 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: Arizona, Colorado, Oklahoma, Alabama, Missouri, Texas, Illinois, Washington, Kansas, New Mexico, Louisiana, Arkansas, California, Alaska, South Dakota, North Dakota, Utah, Nebraska, and West Virginia.

IP addresses

Because the location of an IP address could be some distance from the actual location of your customer, don’t use an IP address alone for determining how much tax to collect. Instead, use the upcoming invoice endpoint to show them an estimate of the tax they’ll pay before collecting a billing or shipping address.

Europe and the European Union (EU)

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.

Canada

In order for Stripe Tax to determine the applicable tax rate and collect tax in Canada, you need to collect the customer’s province or postal code.