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

Automatically collect tax on invoices

Learn how to automatically calculate tax on your invoices.

On an invoice, Stripe Tax calculates sales tax, VAT, and GST. To calculate these for each line item, Stripe uses:

  • Your tax settings
  • The customer’s tax settings and location
  • The product tax code and price tax behavior
Loading video content...

Set up the customer

We use the customer’s location to determine the relevant taxes to collect. Customers outside of the US need at least a country-level address, while customers in the US require a 5-digit postal code. For Canada, we need at least the province or postal code.

To create a customer with the API, send Stripe a description, and as much information as possible to help identify the location and tax requirements for your customer. We recommend populating the customer.address field with your customer’s complete billing address. Validate the customer address upon creation by passing tax[validate_location]=“immediately”. You can also expand the tax field to confirm the location Stripe Tax identified for your customer.

Command Line
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d description="a new user" \
  -d "address[line1]"="510 Townsend St" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"=CA \
  -d "address[country]"=US \
  -d "address[postal_code]"=94103 \
  -d "tax[validate_location]"=immediately \
  -d "expand[]"=tax

You can also add both your customer’s country and postal code:

Command Line
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d description="a new user" \
  -d "address[country]"=US \
  -d "address[postal_code]"=94103 \
  -d "tax[validate_location]"=immediately \
  -d "expand[]"=tax

Or only their IP address:

Command Line
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d description="a new user" \
  -d "tax[ip_address]"="203.0.113.0" \
  -d "tax[validate_location]"=immediately \
  -d "expand[]"=tax

The expanded tax field indicates the computed tax location and if the customer is compatible with automatic tax calculation:

{
  "id": 
"{{CUSTOMER_ID}}"
,
  "object": "customer",
  // ... other fields omitted
  "tax": {
    "location": {
      "country": "US",
      "state": "CA",
      "source": "billing_address"
    },
    "ip_address": null,
    "automatic_tax": "supported",
  }
}

The value of the tax[automatic_tax] parameter has four possible states:

StatusDescriptionPossible Action
supportedAutomatic tax is fully supported.No further action needed.
unrecognized_locationThe address isn’t valid for determining a tax location.Ask the customer for an updated address and set customer.address to the new value.
not_collectingThe address is resolvable to a location for which you haven’t set up a registration.Depending on your tax obligations, you can either proceed and Stripe Tax won’t assess any taxes, or you might want to add a new registration for the jurisdiction the customer is based in.
failedAn error occurred with Stripe’s servers. This is rare.Try the request again, or contact Stripe support for additional assistance.

Set up line items

To calculate tax on each line item on an invoice, you need to set a tax behavior and optionally a tax code.

Customize tax settings for one-off line items

Customize line items in the Invoice Editor by selecting the tax behavior from the Include tax in price drop-down menu.

Customize tax settings for one-off line items

Customize tax settings for one-off line items

Customize tax settings for product-based line items

You can use both the Dashboard and the API to customize tax settings for product-based line items.

Stripe Tax uses information stored on the Products and Prices objects to determine the rates and rules to apply when calculating tax. Update the products and prices you use with Invoices to include:

  • Tax behavior—either inclusive or exclusive. This determines whether or not tax is already included in your pricing. For example, an inclusive line item with an amount of 10 USD totals to 10 USD, whereas an exclusive line item with an amount of 10 USD totals to 10 USD plus tax. Exclusive pricing is common practice in US markets and for B2B sales, while inclusive is common practice for B2C buyers in many markets outside the US. Setting the tax behavior explicitly on a price is optional, if you set up the default tax behavior in the Stripe Tax settings. You can override the default tax behavior setting by setting a tax behavior on a price.

  • Tax code (Optional)—a selection from a list of options that determine what type of product it is. Some examples include “Audio book," “Gift card," or “Software as a service." If you don’t set this explicitly, your preset tax code applies.

Caution

You can’t change tax_behavior after it’s set to either exclusive or inclusive. If you want to change the tax behavior of a price, you need to create a new price with the desired behavior, and archive the old price.

Command Line
curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d unit_amount=5000 \
  -d currency=usd \
  -d tax_behavior=exclusive \
  -d "product_data[name]"="A new product"

Enable automatic tax

After specifying a tax behavior and tax code, you can add the price to the customer as an invoice item:

Command Line
curl https://api.stripe.com/v1/invoiceitems \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "pricing[price]"=
{{PRICE_ID}}

Set the toggle in the Invoice Editor. In the API, you need to pass the automatic_tax field to enable or disable automatic tax calculation. Both steps are required to start calculating tax automatically.

Command Line
curl https://api.stripe.com/v1/invoices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "automatic_tax[enabled]"=true

To enable automatic tax calculation when you update an invoice, add the invoice parameter alongside automatic_tax:

Command Line
curl https://api.stripe.com/v1/invoices/
{{INVOICE_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "automatic_tax[enabled]"=true

See also

Was this page helpful?
YesNo