Adding tax to Stripe Subscriptions

Table of contents
  1. Introduction
  2. How to add tax as an invoice subtotal
    1. Calculate tax amount using Anrok API
    2. Create tax rate with Stripe API
    3. Create subscription with tax rate using Stripe API
    4. Remove tax rate from Stripe subscription using Stripe API
  3. How to add tax as an invoice line item
    1. Create tax product on Stripe
    2. Create subscription with tax as invoice line item using Stripe API

Introduction

The Anrok/Stripe integration automatically adds tax to draft invoices on Stripe. This includes invoices generated on the Stripe dashboard, the API, and recurring invoices generated for subscriptions. The integration does not, however, add tax to invoices that are finalized immediately. This happens most commonly for the first invoice of a new subscription.

This guide walks through the process of calculating tax with the Anrok API and supplying that tax to Stripe when creating a new subscription. This process ensures that tax is added to the first invoice of that subscription. We will cover two different approaches:

  1. How-to add tax as invoice subtotal
  2. How-to add tax as an invoice line item

How to add tax as an invoice subtotal 

    sequenceDiagram
    participant A as App
    participant S as Stripe
    participant K as Anrok
    A->>K: request tax amount for transaction
    K->>A: respond with tax amount
    A->>A: calculate blended tax rate
    A->>S: create tax rate
    S->>A: respond with tax rate ID
    A->>S: create subscription
supply tax_rates
    S->>S: create and finalize first invoice
tax added as subtotal
    S-->>K: send webhook
invoice.created
    K->>K: transaction recorded for filing
    S-->>A: send webhook
customer.subscription.created
    A->>S: update subscription
remove tax_rates

We’ll review the following steps below:

  1. Calculate tax amount using Anrok API
  2. Create tax rate with Stripe API
  3. Create subscription with tax rate using Stripe API
  4. Remove tax rate from Stripe subscription using Stripe API

Calculate tax amount using Anrok API

We will be using Anrok’s createEphemeral endpoint to calculate tax for the first invoice of our subscription. This endpoint accepts transaction details as input and returns the tax amount that needs to be included when creating the Stripe subscription.

To calculate tax, we’ll need this subscription information:

  • Customer address
  • Product IDs and amount for each line item of the subscription
anrok_api_key='sxxx/sakxxx/secret.xxx'

curl https://api.anrok.com/v1/seller/transactions/createEphemeral \
    -H "Authorization: Bearer $anrok_api_key" \
    --json '{
        "accountingDate": "2023-01-01",
        "currencyCode": "USD",
        "lineItems": [{
            "productExternalId": "acme-pro",
            "amount": 1050
        }],
        "customerAddress": {
            "line1": "East 17th Street",
            "city": "New York",
            "region": "NY",
            "postalCode": "10003",
            "country": "us",
        }
    }'

If the request is successful, you’ll receive a response similar to the example below. For a complete overview of the response structure and possible error types, refer to the Anrok API documentation.

{
    "taxAmountToCollect":69,
    "lineItems":[{
        "taxAmountToCollect":69
    }]
}

We’ll use taxAmountToCollect as the tax amount when creating our Stripe Subscription.

Create tax rate with Stripe API

Once we’ve calculated the tax amount to collect with the Anrok API, we use that amount to calculate a Stripe Tax Rate. For example, if our product is $10.50 and the tax amount to collect is $0.69, the rate can be calculated with:

stripe_tax_rate = (69/1050) * 100
stripe_tax_rate = 0.06571429 * 100
stripe_tax_rate = 6.571429

Stripe accepts up-to 4 decimal places for a tax rate, so we’ll also round our rate calculation to 4 decimal places.

stripe_tax_rate = 6.5714

Next, we’ll add the tax rate to Stripe so it can be used when creating our subscription using the Create tax rate API.

stripe_api_key='sk_xxx'
stripe_tax_rate='6.5714'

curl https://api.stripe.com/v1/tax_rates \
  -u $stripe_api_key: \
  -d display_name=Tax \
  -d percentage="$stripe_tax_rate" \
  -d inclusive=false

If the request was successful, Stripe will return a stripe tax ID that we can use in the next step.

{
    "id": "txr_123",
    "object": "tax_rate",
    # ...
}

Create subscription with tax rate using Stripe API

Now we have all the information we need to create a new subscription on Stripe. For this example we’re creating a subscription for a single item, priced at $10.50 per month, and taxed at the rate we generated in the previous step.

  • items[0]: The product/service being purchased
  • items[0][tax_rates][0]: The tax rate created in the previous step
# Recurring item for the subscription
stripe_product_id='prod_xxx'
stripe_product_amount_in_cents='1050'

# Tax rate for the first invoice of the subscription
stripe_tax_rate_id='txr_xxx'

curl https://api.stripe.com/v1/subscriptions \
  -u $stripe_api_key: \
  -d "customer"=$stripe_customer_id \
  -d 'items[0][price_data][product]'=$stripe_product_id \
  -d 'items[0][price_data][unit_amount]'=$stripe_product_amount_in_cents \
  -d 'items[0][price_data][currency]'='usd' \
  -d 'items[0][price_data][recurring][interval]'='month' \
  -d 'items[0][tax_rates][0]'=$stripe_tax_rate_id

Remove tax rate from Stripe subscription using Stripe API

At this point, we’ve created a subscription and that subscription has issued the first invoice with tax. We could finish here, but tax rates change over time. The rate we supplied when creating the subscription may not be correct on future invoices.

To solve this problem, we’re going to remove the tax rate from the subscription itself and let the Anrok/Stripe integration manage the tax for recurring invoices.

We recommend listening for the following Stripe webhook in your application:

  • customer.subscription.created

When this webhook is received, fetch the Stripe Subscription Item ID from the payload at this location:

  • subscription.items.data[0].id

Then, make an API request to the Stripe Subscription Item API to remove the tax rate from the subscription.

stripe_subscription_item_id='si_xxx'

curl https://api.stripe.com/v1/subscription_items/$stripe_subscription_item_id \
  -u $stripe_api_key: \
  -d 'tax_rates'='' \
  -d 'proration_behavior'='none'

If you have multiple subscription line items on your subscription, repeat this process for all items.

How to add tax as an invoice line item 

    sequenceDiagram
    participant A as App
    participant S as Stripe
    participant K as Anrok
    A->>K: request tax amount for transaction
    K->>A: respond with tax amount
    A->>S: create subscription
supply tax in add_invoice_items[]
    S->>S: create and finalize first invoice
tax added as line item
    S-->>K: send webhook
invoice.created
    K->>K: transaction recorded for filing

We’ll review the following steps below:

  1. Create tax product on Stripe
  2. Calculate tax amount using Anrok API
  3. Create subscription with tax as invoice line item using Stripe API

Before you begin, if you have decided to use tax as an invoice line item, email support@anrok.com to update your Stripe integration. This is a required step for this implementation approach.

Create tax product on Stripe

Since we’ll be adding tax as an additional line item on the first invoice of our subscription, we’ll need to create a Stripe product to use for this purpose. This only needs to be done once. The same tax product can be used for all new Stripe subscriptions.

  1. Navigate to add a product on Stripe.
  2. Fill in the product information with these details:
    • Name: Tax
    • Pricing model: Standard Pricing
    • Price: $0.00
    • Frequency: One time
  3. Click “Save product”.

We now have a product ID that we can use for tax when creating a Stripe Subscription.

To use this product ID for tax with your Anrok Stripe integration, email the product ID to support@anrok.com. This is a required step so we can update your Stripe integration with this product ID.

Create subscription with tax as invoice line item using Stripe API

Now that we’ve calculated the tax amount to collect on the first invoice, we can create the subscription using the Stripe API. In this example, we’ll be creating a subscription for one product.

  • items[0]: The product/service being purchased
  • add_invoice_items[0]: The tax amount to collect

Notice we’re supplying tax as an “Add Invoice Item”. An add_invoice_item only appears on the next invoice for the subscription. Supplying tax in this way ensures that tax will appear on the first invoice of the subscription, but will not appear on any recurring invoices. Recurring invoices will have tax added automatically by the Anrok/Stripe integration.

# Recurring item for the subscription
stripe_product_id='prod_xxx'
stripe_product_amount_in_cents='1050'

# Tax amount for the first invoice of the subscription
stripe_tax_product_id='prod_xxx'
anrok_tax_amount_to_collect='69'

curl https://api.stripe.com/v1/subscriptions \
  -u $stripe_api_key: \
  -d "customer"=$stripe_customer_id \
  -d 'items[0][price_data][product]'=$stripe_product_id \
  -d 'items[0][price_data][unit_amount]'=$stripe_product_amount_in_cents \
  -d 'items[0][price_data][currency]'='usd' \
  -d 'items[0][price_data][recurring][interval]'='month' \
  -d "add_invoice_items[0][price_data][product]"=$stripe_tax_product_id \
  -d "add_invoice_items[0][price_data][unit_amount]"=$anrok_tax_amount_to_collect \
  -d "add_invoice_items[0][price_data][currency]"='usd'