Automatically collect tax on invoices

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.

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:

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:

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:

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.

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"

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

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.

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:

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