Using Avalara’s AvaTax with Stripe Subscriptions

It’s supposed to be easy. Eventually, it is.

If you use Stripe to charge users and plan on using Avalara’s AvaTax for charging sales tax, you’re probably looking for a simple plug & play solution. It very much is this type of solution, but it isn’t very well documented.

This post is all about laying out the required steps to making it work quickly and easily.

Examples are written in node.js but can easily be converted to any language Stripe’s API supports.

First Step: Ask Stripe to Allow Your Account to Use The pay_immediately flag

Contact Stripe’s support and ask them to enable the usage of the pay_immediately flag for you for the purpose of integrating AvaTax.

For AvaTax to integrate with Stripe, you have to give AvaTax to a chance to catch new invoices and add the sales tax to the invoice. You do this by sending the attribute pay_immediately = false upon subscription creation. This flag is not well documented anywhere and is disabled by default.
Avalara do mention it in their documentation, but it’s easy to miss.

Second Step: Update Address Details in The Customer’s Metadata

Add address details that AvaTax will use to calculate the tax for future invoices. This can happen at any time prior to creating the subscription.
Only Address_PostalCode and Address_Country are mandatory but you can add more details to make the tax calculation more accurate.

const stripe = require('stripe')(STRIPE_KEY);

const customer = await stripe.customers.update(
  CUSTOMER_ID,
  { metadata: {
      'Address_PostalCode': '10001', // Valid Postal Code
      'Address_Country': 'US' // ISO-3166-1 alpha-2 Country Code
    }       
  }
);

Third Step: Add The pay_immediately = false to Your Subscription Creation Request

When you create the subscription, add the attribute pay_immediately with the value false.

const stripe = require('stripe')(STRIPE_KEY);

const subscription = await stripe.subscriptions.create({
  customer: CUSTOMER_ID,
  items: [
    {price: PRICE_ID},
  ],
  pay_immediately: false
});

Fourth Step: Wait for Webhook Events

Your invoice will not be charged immediately (as you requested), and AvaTax will pick it up. This could take a couple of seconds.
Avalara’s webhooks will allow you to know what happened with your invoice under their care.

That’s it. It’s fairly easy and straightforward, but it’s rather hard to find good documentation for it.

Comments

[Rita {FlyNerd} Lyczywek]

Thank you!
Support enabled the feature (they claim), how to confirm that, or how did you handle missing pay_immediately in the type in Stripe create method?

Argument of type '{ default_payment_method: string; customer: string; items: { price: string; }[]; expand: string[]; pay_immediately: boolean; }' is not assignable to parameter of type 'SubscriptionCreateParams'.
  Object literal may only specify known properties, and 'pay_immediately' does not exist in type 'SubscriptionCreateParams'.

[Rita {FlyNerd} Lyczywek]

the only way is to add //@ts-ignore

[Julien Vanier]

The detail about pay_immediately = false is exactly what I was missing. Thanks for writing this up!