Collect customer addresses

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.

Which 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 an automatic tax calculated payment used in the Automatic tax calculation section of the Transactions details page in your Dashboard.

You can also review the tax.location.source field on the Customer API object.

Checkout and Payment Links

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

Invoicing, Subscriptions, and custom payment integrations

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.

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

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

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.

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.

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

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.

Wilayah yang dikecualikan

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.

Best practices for collecting customer addresses

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.

• Use two-letter country codes (ISO 3166-1 alpha-2).
• Listen for subscription webhook events as most activity happens asynchronously.

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

If you have a customer address, or can collect one, update the customer and finalize the invoice manually.

If you don’t have a customer address or can’t collect it, disable Stripe Tax for the invoice and its subscription, and finalize the invoice manually.

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