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

When we can’t finalize an invoice because of an unrecognized customer location, we send an invoice.finalization_failed event with the invoice last_finalization_error[code] being customer_tax_location_invalid. This might happen if you didn’t provide tax[validate_location]="immediately" while creating or updating a customer.

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.