Collect taxes for recurring payments

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

1. Tax behavior: The tax behavior on a price can be either inclusive or exclusive. This determines how the buyer sees the tax. When you set tax behavior to exclusive, it adds tax onto the subtotal amount you specify on your price. This is common in US markets and for B2B sales. When set to inclusive, the amount your buyer pays never changes, even if the tax rate varies. This 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.

2. (Optional) Tax code: A tax code is a classification of your product or service for Stripe Tax that makes sure we apply the correct tax rate to your transactions. Some examples include “Audio book,” “Gift card,” or “Software as a service.” If you don’t set the tax code, Stripe Tax uses the preset tax settings.

If you don’t want to create your products and prices upfront, you can pass price_data.tax_behavior and product_data.tax_code when creating subscriptions.

Learn more about Products, prices, tax codes, and tax behavior.

This guide uses an e-magazine as an example of a product with a recurring payment.

First, create a Price on your server with a monthly charge for a new Product named “My Product”. For tax purposes you add two extra fields:

• tax_behavior on the Price object. Set to inclusive or exclusive. This is a required field if you are using Stripe Tax with Subscriptions.
• tax_code on the Product object. A Stripe tax code, which maps to a product tax code. Consult our list of tax codes for more information.

curl https://api.stripe.com/v1/products \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="My Product" \
  -d tax_code=
txcd_10000000

Record the product ID for the product. It looks like this:

{
  "id": "prod_H94k5odtwJXMtQ",

Use the product ID to create a price.

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d unit_amount=1000 \
  -d currency=usd \
  -d "recurring[interval]"=month \
  -d product=prod_H94k5odtwJXMtQ \
  -d tax_behavior=exclusive

Record the price ID so it can be used in subsequent steps. It looks like this:

{
  "id": "price_HGd7M3DV3IMXkC",

When a user subscribes to your website, create a Customer on your server.

When creating a customer, you can just send us a description and the payment method. However, the more information you send us, the better the tax calculation can identify the location of your customer and tax them accordingly. We recommend populating the customer.address field. Expand the tax field to confirm the location Stripe Tax has identified for your customer.

You can either add a country and a postal code:

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d description="a new user" \
  --data-urlencode email="franklin@example.com" \
  -d payment_method=pm_1FU2bgBF6ERF9jhEQvwnA7sX \
  -d "address[country]"=US \
  -d "address[postal_code]"=94103 \
  -d "expand[]"=tax

Or, ideally, add a complete billing address:

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d description="a new user" \
  --data-urlencode email="franklin@example.com" \
  -d payment_method=pm_1FU2bgBF6ERF9jhEQvwnA7sX \
  -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 "expand[]"=tax

Or, just an IP address:

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d description="a new user" \
  --data-urlencode email="franklin@example.com" \
  -d payment_method=pm_1FU2bgBF6ERF9jhEQvwnA7sX \
  -d "tax[ip_address]"="127.0.0.1" \
  -d "expand[]"=tax

The expanded tax field indicates the computed tax location (using the address first, falling back on the given IP address) and if the customer is compatible with automatic tax calculation:

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

The value of automatic_tax has four possible states:

Now that the Customer is set up for tax calculation, you can create a Subscription on your server with the customer and their selected plan. To enable automatic tax calculation on subscriptions, set the automatic_tax[enabled] parameter to true:

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer=cus_13729he8947269 \
  -d "items[0][price]"=price_HGd7M3DV3IMXkC \
  -d "items[0][quantity]"=1 \
  -d "automatic_tax[enabled]"=true \
  -d payment_behavior=default_incomplete \
  -d "expand[0]"=latest_invoice

Setting this parameter causes all subsequent Invoices to be created with automatic tax calculations activated.

To inspect the results of the latest tax calculation, retrieve the latest Invoice of a Subscription. You can do this by expanding the latest_invoice field on any Subscription request, as in the examples above. You can retrieve the tax amounts from the tax and total_tax_amounts fields on the latest invoice, and also from the per-line item tax_amounts fields.

If Stripe Tax does not have enough information to determine the customer’s location, a customer_tax_location_invalid error is returned.

To complete payment of the first invoice and activate the subscription, use stripe.confirmCardPayment when your customer submits the form.

const btn = document.querySelector('#submit-payment-btn');
btn.addEventListener('click', async (e) => {
  e.preventDefault();
  const nameInput = document.getElementById('name');

  // Create payment method and confirm payment intent.
  stripe.confirmCardPayment(clientSecret, {
    payment_method: {
      card: cardElement,
      billing_details: {
        name: nameInput.value,
      },
    }
  }).then((result) => {
    if(result.error) {
      alert(result.error.message);
    } else {
      // Successful subscription payment
    }
  });
});

The subscription automatically becomes active upon payment. See our Subscriptions with Elements guide for more details on setting up your checkout page.