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.

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.

• Collect and set both the country and the postal_code fields on your customer objects.
• Use two-letter country codes (ISO 3166-1 alpha-2).
• When creating or updating a customer, set tax[validate_location]=“immediately” to prevent customer_tax_location_invalid errors later.
• Listen for subscription webhook events as most activity happens asynchronously.

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 it, update the customer and finalize the invoice manually.
  1. Update the customer with tax[validate_location]=“immediately” to make sure that the new address is valid.
  2. Finalize the invoice.
• 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.