This integration connects HubSpot to your Avalara AvaTax account and calculates sales tax for you in real time, right on your Deals, Quotes, Invoices, Payment Links, and Subscriptions.
If you haven't already, pay the setup fee to get your AvaTax for HubSpot portal login. The portal is our app, and it's how you connect HubSpot to Avalara. Questions? Email us anytime at avataxforhubspot@taxiom.com.
Two ways to learn the integration
Watch the 10-minute walkthrough, or scroll down to the written guide for step-by-step detail on every feature.
Prefer reading? Skip to the written guide ↓
Want us to walk you through it on a live call? Add our Guided Setup add-on ($299) — two calls with our team, up to 45 minutes each. Add Guided Setup — $299
Jump to a section:
1. Install & Connect Avalara 2. Configure Your Portal Settings 3. Your First Tax Calculation 4. Quotes, Invoices, Payment Links & Subscriptions 5. Tax Codes & Product Mapping 6. Exemptions & Customer Codes 7. Ship-To Address 8. Different Ship-To Addresses on One Deal 9. Multiple Ship-From Locations (Warehouses) 10. Multi-Company Entity Routing 11. Per-Line Tax Overrides 12. Status Field & Errors Log 13. Self-Serve Admin & Receipts 14. Calculating Tax from Outside HubSpot (Pre-Calc API) 15. Frequently Asked Questions 16. Troubleshooting & Support Key HubSpot Properties ReferenceEverything here starts with a HubSpot Deal. Whatever you send a customer, whether it's a Quote, an Invoice, a Payment Link, or a Subscription, you create it from the Deal, and the tax comes along with it. The rhythm is simple:
Once that pattern clicks, the rest of this guide is just settings and special cases. If you need to calculate tax outside HubSpot — from your own backend, a custom checkout, or an ERP — see Section 14 for our Pre-Calc API.
Before you start, you'll need three things:
Sign in to avataxforhubspot.taxiom.com with the login we sent you. Click Connect HubSpot App in the left menu, choose the HubSpot account you want to connect, review what it asks for, and approve. You'll come back to the portal once it's done.
In the portal sidebar, click Company Settings and enter the address you usually ship from (street, city, state/region, postal code, country). Click Save Info. Tax can't calculate without this — Avalara needs to know where the order starts from to pick the right rates. Ship from more than one place? See Section 9.
Back in the sidebar, click Avalara Credentials. Enter your Account Number, License Key, and Company Code, choose Production or Sandbox, and click Save Info.
The Sync Settings page is where you choose how tax shows up in HubSpot and which automatic behaviors are turned on.
This is the most important setting on the page. It decides when the integration tells Avalara to treat a transaction as committed (counted in your filings and reports) versus uncommitted (visible in Avalara to look at, but not filed). The right choice depends on where you actually collect payment:
Collecting payment outside HubSpot but still want commits? Pick "Commit when the Quote/Invoice is paid," then mark the Invoice as paid in HubSpot once the money lands (check, ACH, wire, whatever). The integration treats that the same as a HubSpot payment and commits from there.
VAT / international: for VAT-style tax, set "Prices include tax" and change the Tax Label to "VAT." If you fill in the Ava_VAT_Registration_No and Ava_Transport properties on a Company, the integration reads them automatically.
After setup, tax just happens. Add or change a product on a Deal, and as long as the delivery address is complete, the integration figures out the tax on its own. There's no button to press.
Open a Deal, go to its Line Items page, add a taxable product, and within about 10 seconds you'll see a Sales Tax line appear with the amount.
Tax not what you expected?
Nine times out of ten it's the buyer's address. Avalara needs at least City, State, Zip, and Country. If something went wrong, you'll get an email about it.
The tax amount itself comes from your Avalara settings — the integration just sends the order over. If the number looks off, check three things in Avalara: which states you're set up to collect in (your nexus), how your products are mapped to Avalara tax codes, and whether the customer has an exemption on file.
In short, Avalara decides the tax; this integration connects HubSpot to Avalara. See Section 15 — Frequently Asked Questions for a fuller answer.
Always make line item changes on the Deal, not on a Quote or Invoice. The Deal's Line Items page is the only place tax recalculates. Editing a Quote, Invoice, Payment Link, or Subscription directly will not trigger a fresh calculation. The right order is: open the Deal → change the line items there → let tax update → then create or recreate the Quote, Invoice, etc.
Yes, Payment Links and Subscriptions are supported — with one rule that matters: always create them from the Deal's Line Items page. Open the Deal, go to the Line Items panel, wait for tax to finish (you'll see the Sales Tax line fill in), and only then use the Create button to make a Quote, Invoice, Payment Link, or Subscription. Whatever you create carries over the Deal's line items, including the Sales Tax line, so it's correct from the start.
Don't create Payment Links, Subscriptions, Quotes, or Invoices straight from the Commerce or Payments menu. Those skip the Deal's line items, so the integration never gets to add the Sales Tax line, and your customer's total will be missing tax.
From the Deal's Line Items page, click Create → Quote or Create → Invoice. It carries over all the Deal's line items, including the Sales Tax line. When you publish the Quote or send the Invoice, the customer already sees the tax.
From the same Line Items page, click Create → Payment Link. HubSpot makes a Payment Link with all the line items and the Sales Tax line built in. Share it with your customer to collect payment.
Why this works: HubSpot doesn't give integrations a way to hook into a Payment Link directly. Tax shows up on yours because HubSpot copies the Deal's line items (which already include the Sales Tax line) into the link. Just make sure the Deal's tax has finished calculating before you create the Payment Link.
From the Line Items page, click Create → Subscription and set the billing frequency, start date, and recipient. The integration adds a Sales Tax line to the Subscription itself, so every recurring invoice HubSpot generates includes it.
One Subscription limitation to know: because of current HubSpot API limits, the integration can only calculate tax on the first invoice from a Subscription. After that, HubSpot just copies the same Sales Tax amount onto each new invoice instead of recalculating. That's fine when nothing changes (same address, same products, same rates), but if any of those change partway through, the later invoices will show old tax. The workaround: create a new Deal, add the line items there so tax recalculates fresh, then create a new Subscription from that Deal. Editing the existing Subscription's line items won't recalculate, and editing the original Deal won't update a Subscription that's already been created. We're tracking this and will fix it as soon as HubSpot opens up the right API.
Different products are taxed differently, and Avalara needs to know which is which. By default, everything is treated as physical goods (code P0000000). For anything taxed differently — services, software, food, and so on — set the Ava_TaxCode property on the HubSpot Product.
Open the Product, click View all properties, search for Ava_TaxCode, and enter the Avalara code for that product (for example, SW500300 for downloadable software). The integration uses it on the next calculation.
You can browse Avalara's full tax code list at taxcode.avatax.avalara.com.
There are two ways to handle tax-exempt customers. The first is strongly recommended because Avalara checks the actual exemption certificate every time it calculates. The second is a manual override — use it only when the first isn't an option.
The integration automatically sends the HubSpot Company's record ID to Avalara as the customer code on every transaction. So if you upload exemption certificates in Avalara against that same customer code, Avalara checks the certificate on every calculation and applies the exemption automatically — but only when the certificate is current and valid for that location.
How to set it up:
This is the better path because Avalara owns the certificate — it tracks expiration dates, checks which jurisdictions it covers, and keeps an audit trail that holds up if you're ever examined.
Certificate filed under a different code? By default, the integration uses the HubSpot Company's record ID as the Avalara customer code. If your certificate in Avalara is filed under a different customer code, set Ava_CustomerCode on the HubSpot Company and the integration will use that instead — so the customer code on the transaction matches the one on your certificate.
If you manage a lot of certificates (uploads, renewals, multi-state tracking, customer self-service), Avalara's full Exemption Certificate Management or ExemptHQ from Taxiom add purpose-built tools on top of the same matching.
Ava_EntityUseCode on the HubSpot CompanyIf you haven't set up certificates in Avalara yet, or you need a quick manual override, set the Ava_EntityUseCode property on the HubSpot Company. Avalara understands the standard letter codes (A = Federal government, B = State/local government, C = Tribal government, D = Foreign diplomat, E = Charitable, F = Religious/educational, G = Resale, and so on).
Open the Company, click View all properties, search for Ava_EntityUseCode, and enter the right letter. The next calculation marks the applicable lines exempt.
Why this is the fallback, not the recommendation: an entity use code tells Avalara "trust me, this customer is exempt," and Avalara marks it exempt without checking for an actual certificate. That's quick, but it leaves you exposed in an audit if you don't have the paperwork to back it up. Whenever you can, upload the real certificate in Avalara (Method 1) and let Avalara do the verifying.
The entity use code above applies to the whole customer. If you only need to exempt one line item, or use a different code on a specific line, set the Ava_LineUseCode property on that line item from the Deal's Line Items page. It uses the same letter codes as above, and it overrides the company-level code for that line only — everything else on the Deal is taxed normally.
Don't see the Ava_LineUseCode column on the Line Items table? Click Actions → Edit columns, search for it, and add it.
Sales tax depends on where an order is going, so the integration always needs a delivery address. It looks for one in this order:
If a Deal ships somewhere other than the company's normal address — a job site, for example — turn on Use Deal Ship-To in Sync Settings, then fill in the five Ava_Deal Ship-To fields (Line 1, City, Region/State, Postal Code, Country) on the Deal.
With this on, the integration uses the Deal's address whenever it's filled in. If you leave the Deal's fields blank, it simply falls back to the Company address (and then the Contact address) — so turning this on won't break the Deals that don't need a special address.
To find these fields, open the Deal and click View all properties in the right sidebar (or Actions → View all properties at the top), then search for Ava_Deal to see all five Ship-To fields.
Want to require the Deal address? Right below the first option is a stricter one, Require Deal Ship-To. Turn it on when a Deal's address must never quietly fall back to the company — if the Deal's ship-to fields are blank, the integration stops and emails you instead of using a different address. Leave it off (the default) to allow the automatic fallback described above. This is handy for B2B job-site work where using the wrong address would mean the wrong tax.
Sometimes one order ships to more than one place. A customer might buy five items on a single Deal and want three sent to their head office and two to a job site in another state. Since sales tax depends on where each item is delivered, those destinations can be taxed differently. The integration handles this for you: each line item can have its own ship-to address, and Avalara taxes each line based on where that line is going.
To use it, fill in the ship-to fields only on the lines that go somewhere different. Every line item has five address fields:
Ava_ShipToStreetAddressAva_ShipToCityAva_ShipToStateAva_ShipToPostalCodeAva_ShipToCountryAnything you leave blank falls back to the Deal's regular ship-to address (the one from Section 7). So a line where you enter only a different city, state, and zip will still borrow the street and country from the Deal. And a line where you fill in nothing just ships to the Deal's main address, like normal. You only enter what's different.
Set these on the Deal's Line Items page, like every other line-item field. If you don't see the Ava_ShipTo... columns on the Line Items table, click Actions → Edit columns, search for them, and add them.
The per-line address stays correct through the whole process — the first calculation, the commit when the Invoice is paid or created, and any refund — so your Avalara filings reflect the right tax for each destination.
If you ship from more than one location, you can add each warehouse in Company Settings and pick the right one per line item. Avalara uses the ship-from address to handle origin-based tax in the states where that matters.
In the AvaTax portal, go to Company Settings, check "Click here if you have multiple Ship From locations such as warehouses", then add each location with a code (for example, TX01), a name, and the full address. Back in HubSpot, each line item gets an Ava_ShipFromLocation dropdown to choose the source warehouse. If you don't pick one, the default company address is used.
Don't see the Ava_ShipFromLocation column on the Line Items table? Click Actions → Edit columns, search for it, and add it.
If your business runs under more than one legal entity, each with its own Avalara company code (say, a US company and an EU company), you can send each Deal to the right Avalara company based on a HubSpot Deal property.
In Sync Settings, scroll to Entity Routes. Choose the Deal property the integration should read (for example, a custom bc_entity property), then add a row for each value (for example, "Acme USA Inc" → ACMEUSA). When a Deal calculates, the integration reads that property and sends the calculation to the matching Avalara company.
This is an advanced feature — most customers use a single Avalara company code and can skip this section. Email avataxforhubspot@taxiom.com if you'd like help setting it up.
For special cases where you need to set the tax amount on a specific line yourself (a negotiated amount, or tax you've worked out manually for an unusual jurisdiction), set the Ava_OverrideTaxValue property on that line item from the Deal's Line Items page. The integration tells Avalara to use that exact amount instead of calculating it. Like every other change, do this on the Deal — an override on a downstream Quote, Invoice, or Subscription line won't take effect.
Don't see the Ava_OverrideTaxValue column on the Line Items table? Click Actions → Edit columns, search for it, and add it. Same goes for Ava_LineUseCode and Ava_ShipFromLocation — any line-item Ava field has to be added through Edit columns before you can see and edit it.
Important: set the override on the actual product line (for example, the Test Product line), not on the auto-managed "Sales Tax" line. The Sales Tax line exists only to display the total; an override there is ignored. To clear an override and go back to Avalara's calculated amount, just empty the cell.
Every record the integration touches gets an ava_tax_status property with one of three values:
The full history lives in Errors Logs in the AvaTax portal. Every failed calculation records what went wrong, the message, the Deal/Quote/Invoice it relates to, and the time.
The most common errors:
Ava_TaxCode Avalara doesn't recognizeThe Admin page in the portal sidebar is where you manage your account details and find your receipts.
If you create Quotes or Invoices outside of HubSpot — from a custom checkout, an ERP, or your own product — the Deal-based flow above doesn't apply. For those cases we offer a Pre-Calc API as a paid add-on.
You call our endpoint with the line items and ship-to address before you create your invoice. We run the tax through Avalara using your own credentials and send back the Sales Tax amount, ready to drop into your invoice.
If that fits your setup, email avataxforhubspot@taxiom.com with a quick description and we'll send pricing, docs, and access.
The Pre-Calc API is built for high-volume, automated flows. If you only create a few invoices outside HubSpot, you can copy the line items into a HubSpot Deal, let the integration calculate tax, and read the Sales Tax value off the Deal.
Three things — and all three live in your Avalara account, not in this integration:
The integration's job is to send Avalara the right details — what's being sold, where it's going, and who's buying. Avalara applies the three rules above and tells us the tax. If you're seeing $0 when you expected a charge (or an amount you didn't expect), the answer is almost always in those three Avalara settings, not in the integration.
Avalara needs to see every transaction — even the $0 ones — to track your nexus across all states. Even where you're not registered yet, each sale still counts toward whether you've crossed an economic-nexus threshold there. Keeping the Sales Tax line on every Deal also gives you one consistent process: every invoice is handled the same way, with no one-off decisions about whether to "add tax this time."
HubSpot's built-in tax fields on Quotes and Invoices aren't open to outside integrations — we couldn't get the access from HubSpot to write into them. So instead, the integration adds a dedicated Sales Tax line item. That lets us both trigger the calculation and make sure the tax adds correctly into the Deal/Quote/Invoice total. Your customer sees a clean "Sales Tax" line, and the math works out.
That $0 is just a sign that it's recalculating. When you change a line item on the Deal, the integration clears the old amount, asks Avalara for a fresh one, and writes it back — usually within 5-10 seconds. You'll also see ava_tax_status go from "calculated" to "pending" and back during that moment.
Usually 5-10 seconds. The clock starts when HubSpot tells us about the change and stops when the Sales Tax line updates. If nothing happens after 30 seconds, check the Errors Logs in the portal.
Two likely reasons: (1) the "Auto-calculate only for US-based Deals and Subscriptions" toggle is on in Sync Settings, so the integration is skipping non-US Deals on purpose; or (2) the Company or Contact's country field is blank, so the integration can't tell where the order is going and treats it as non-US. Check that toggle in Sync Settings, and make sure the Company or Contact has a country filled in.
Usually it's because a HubSpot workflow fills in the address a few seconds after the Deal is created — by the time it finishes, the integration has already tried and failed once. Turn on Mute error notification emails in Sync Settings. Errors are still saved in the portal, but your reps stop getting emails for hiccups that fix themselves.
By default, the integration sends draft calculations as SalesOrder transactions. They cost about 1/10 of a full SalesInvoice and don't count toward your filings, and they show as "Temporary" in Avalara. Once the customer pays (or the Quote/Invoice commits), the integration upgrades it to a SalesInvoice and commits it for filing. The Commit Interval in Sync Settings controls when that happens.
Yes. Change Tax Label in Sync Settings to whatever fits — "VAT," "GST," "Tax," etc. It shows up on customer-facing Quotes, Invoices, and Payment Links wherever the tax line appears.
Once a HubSpot Invoice goes from draft to "open" (sent to the customer), HubSpot locks in the subtotal, billed amount, and tax. There's no public HubSpot way to force a recompute on a sent Invoice. The integration can still write a new tax value, but HubSpot keeps showing the original amount the buyer saw. The cleanest fix: void the Invoice, edit the source Deal's line items, and create a fresh Invoice from the updated Deal.
Yes — it's a known HubSpot API limit, not a bug. Tax is calculated on the first invoice from a Subscription. Each later invoice copies the same line items (including the Sales Tax line at its original value), so the tax stays the same across billing cycles. That's correct for stable subscriptions, but if the customer's address, product taxability, or rates change partway through, the later invoices will show old tax. The fix: create a new Deal, add the updated line items there so tax recalculates, then create a new Subscription from that Deal. Editing the existing Subscription's line items does nothing, and editing the original Deal won't flow into a Subscription that already exists. We'll close this gap as soon as HubSpot gives us the access we need.
If something isn't working, check these in order:
ava_tax_status property on the Deal/Quote/Invoice. If it says "failed," that's your starting point.Ava_Deal Ship-To fields are filled in).If you've checked all of that and tax still isn't calculating, email avataxforhubspot@taxiom.com with the Deal/Quote/Invoice link and a quick note on what you expected versus what happened. We reply the same day, usually within a couple of hours.
| Property | Object | Purpose |
|---|---|---|
ava_tax_status | Deal / Quote / Invoice / Subscription | calculated / pending / failed |
send_to_avalara | Deal / Quote / Invoice / Line Item | Manual trigger dropdown ("request" to fire a calc) |
Ava_TaxCode | Product | Avalara tax code for this product (defaults to P0000000) |
Ava_EntityUseCode | Company | Exemption code (A-N) for tax-exempt buyers |
Ava_CustomerCode | Company | Override the Avalara customer code (defaults to the HubSpot Company ID) |
Ava_VAT_Registration_No | Company | VAT registration number (for VAT-style markets) |
Ava_Transport | Company | Transport terms for international shipments |
Ava_Deal Ship-To Line 1 / City / Region / Postal Code / Country | Deal | Deal-level ship-to override (5 properties) |
Ava_ShipToStreetAddress / City / State / PostalCode / Country | Line Item | Per-line ship-to address — lets one Deal ship to multiple destinations (see Section 8) |
Ava_ShipFromLocation | Line Item | Pick which warehouse this line ships from |
Ava_OverrideTaxValue | Line Item | Override the calculated tax amount for this line |
Ava_LineUseCode | Line Item | Per-line exemption code (overrides company-level) |
Ava_InvoiceMessages | Deal | Informational messages returned by Avalara (auto-populated) |
Ava_VAT_Codes | Deal | VAT codes returned by Avalara (auto-populated) |