Collect taxes for recurring payments

Use our official libraries for access to the Stripe API from your application:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

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

1. Tax behavior: either inclusive or exclusive. This determines whether tax should be included in the price. 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 + 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.
2. (optional) Tax code: 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 this isn’t set explicitly, your default tax code applies.

If you don’t need to create your products and prices upfront, you can pass price_data.tax_behavior and product_data.tax_code when creating subscriptions. See Products, prices, tax codes, and tax behavior to learn more.

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. 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" \
  -d "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" \
  -d "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" \
  -d "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?expand[]=latest_invoice \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="cus_13729he8947269" \
  -d "items[0][price]"="price_HGd7M3DV3IMXkC" \
  -d "automatic_tax[enabled]"="true" \
  -d "payment_behavior"="default_incomplete"

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.

The Invoice will have an automatic_tax field showing the status of the calculation, with one of three possible states:

If the tax calculation fails during a Subscription request that creates and pays an Invoice, the API returns an HTTP status 400 response.

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.