This integration connects HubSpot to your Avalara AvaTax account, calculating real-time sales tax for Deal → Subscriptions, Invoices, and Payment Links.
If you haven't already, pay the setup fee to receive your AvaTax for HubSpot portal credentials. The portal (our integration) is how you'll connect HubSpot to Avalara. If you have any questions, please email us at avataxforhubspot@taxiom.com.
Two ways to learn the integration
Take 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 ↓
Prefer to have us walk you through this 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 Resolution 8. Multiple Ship-From Locations (Warehouses) 9. Multi-Company Entity Routing 10. Per-Line Tax Overrides 11. Status Field & Errors Log 12. Self-Serve Admin & Receipts 13. Calculating Tax from Outside HubSpot (Pre-Calc API) 14. Frequently Asked Questions 15. Troubleshooting & Support Key HubSpot Properties ReferenceThe integration is built around HubSpot Deals. Every Quote, Invoice, Payment Link, and Subscription you generate flows from a Deal's Line Items page. The pattern is:
Once you understand that pattern, everything else in this guide is configuration and edge cases. If you need to integrate from outside HubSpot - directly from your own backend, custom checkout, or ERP - see Section 13 for our Pre-Calc API option.
Before you begin, you'll need:
Sign in to avataxforhubspot.taxiom.com with the credentials you received. Click Connect HubSpot App in the left menu, pick the HubSpot account you want to install into, review the scopes, and approve. You'll land back on the integration portal once the install completes.
In the integration portal sidebar, click Company Settings and enter your business's default ship-from address (street, city, state/region, postal code, country). Click Save Info. Tax calculations cannot run without this - Avalara needs an origin address to determine which jurisdiction's rates to apply. If you ship from multiple warehouses, 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 control how tax displays in HubSpot and which automation behaviors are turned on for your portal.
This is the most consequential setting on the page. It controls when the integration tells Avalara to treat a transaction as committed (counted toward your filings and liability reports) vs. uncommitted (visible in Avalara for inspection but not filed). Where you actually collect payment dictates which option fits:
Accepting payment outside HubSpot but still want commits to flow? Pick "Commit when the Quote/Invoice is paid" and manually mark the Invoice as paid in HubSpot once the payment lands (check, ACH, wire, etc.). The integration treats a manual mark-paid the same as a HubSpot Commerce payment and commits to Avalara from there.
VAT / international: for VAT-style tax treatment, set "Prices include tax" and change the Tax Label to "VAT". The Ava_VAT_Registration_No and Ava_Transport properties on Company records are read automatically when present.
Once installed, the integration calculates tax automatically whenever a line item is added or changed on a Deal with a complete ship-to address. You don't have to push a button on each one - it just runs.
Open a HubSpot Deal, go to its Line Items page, add a taxable product, and within ~10 seconds you'll see a Sales Tax line appear with the calculated amount.
Tax calculation not what you expected?
If tax calculation didn't work, check the company address of your buyer as that's usually the cause. Avalara requires at a minimum City, State, Zip Code, & Country. You'll get an email if the integration ran into an error.
Your Avalara settings dictate the tax that comes back, the integration just sends over the transaction. If the amount looks off, check three things – which states you have turned on for tax calculation (Nexus) in AvaTax, your product/Avalara tax code mapping, and whether you have an exemption for the customer in Avalara.
Avalara controls the tax assessment; this integration just connects HubSpot to Avalara. See Section 14 — Frequently Asked Questions for a deeper answer.
Always make line item adjustments on the Deal, not on a downstream object. The Deal's Line Items page is the only place where the integration can recalculate tax. Editing a Quote, Invoice, Payment Link, or Subscription directly will not trigger a fresh tax calculation. The correct flow is: open the Deal → adjust line items there → let tax recalculate → only then create or regenerate the downstream object.
Yes, the integration supports Payment Links and Subscriptions - but the workflow has one rule that matters: every downstream object must be created from the Deal's Line Items page. Open the Deal, click into the Line Items panel, let the integration finish calculating tax (you'll see the Sales Tax line populate), and only then use the Create button to spin off a Quote, Invoice, Payment Link, or Subscription. The new object inherits the Deal's line items - including the auto-managed Sales Tax line - so tax is correct out of the gate.
Don't create Payment Links, Subscriptions, Quotes, or Invoices directly from the Commerce or Payments menu in HubSpot. Those paths bypass the Deal's line items, so the integration has no chance to inject the Sales Tax line and your customer-facing total will be missing tax.
From the Deal's Line Items page, click Create → Quote or Create → Invoice. The new object inherits all the Deal's line items including the auto-managed Sales Tax line. When you publish the Quote or send the Invoice, your customer sees the tax already calculated.
From the same Line Items page, click Create → Payment Link. HubSpot generates a Payment Link that includes all line items, with the Sales Tax line built in. Share the link with your customer to collect payment.
How Payment Links work behind the scenes: HubSpot doesn't expose a Payment Link object the integration can hook into. Tax appears on your Payment Link because HubSpot copies the Deal's line items (which already include the calculated Sales Tax line) into the link. Make sure the Deal's tax has fully calculated before generating the Payment Link.
From the Line Items page, click Create → Subscription and configure the billing frequency, start date, and recipient. The integration seeds a Sales Tax line on the Subscription itself, so every recurring Invoice HubSpot generates will include it.
Important Subscription limitation: Because of current HubSpot API access limitations, the integration can only calculate tax on the first Invoice generated from a Subscription. The recurring Invoices HubSpot creates after that do not automatically recalculate tax - HubSpot just copies the original Sales Tax line value into each new Invoice. This is fine as long as nothing changes (same address, same products, same tax rates), but if any of those change mid-Subscription, the recurring Invoices will show stale tax. The recommended workaround: create a new Deal, add the line items to that new Deal so the integration calculates fresh tax, then create a new Subscription from that new Deal. Editing the existing Subscription's line items will not trigger a recalc, and editing the original source Deal's line items won't propagate to the already-created Subscription either. We're tracking this as a known gap and will close it as soon as HubSpot exposes the right API.
Avalara assigns different tax rates based on what's being sold. By default, every line item is treated as tangible personal property (code P0000000). For products that have a different treatment (services, software, food, etc.), set the Ava_TaxCode property on the HubSpot Product record.
Open the HubSpot Product, click View all properties, search for Ava_TaxCode, and enter the Avalara tax code for that product (e.g., SW500300 for downloadable software). The integration picks it up automatically on the next calculation.
You can browse the full Avalara tax code catalog at taxcode.avatax.avalara.com.
You have two ways to handle tax-exempt customers. The first method is strongly recommended because it lets Avalara verify the exemption certificate at calculation time. The second is a manual override - use it only when the first method isn't an option.
The integration automatically passes the HubSpot Company's record ID to Avalara as the customer code on every transaction. That means if you upload exemption certificates in Avalara against that same customer code, Avalara's tax engine will check the certificate's validity on every calculation and apply the exemption automatically - only when the certificate is current and applicable to the jurisdiction.
The flow:
This is the better path because Avalara owns the certificate validation - it tracks expirations, jurisdictional applicability, and produces an audit trail that holds up under exam.
If you have a high volume of certificates to manage (uploads, expirations, multi-jurisdiction tracking, customer self-service), Avalara's full Exemption Certificate Management product or ExemptHQ from Taxiom add purpose-built tooling on top of the same matching mechanism.
Ava_EntityUseCode on the HubSpot CompanyIf you don't have certificate management set up in Avalara yet, or you need a quick manual override, set the Ava_EntityUseCode property on the HubSpot Company record. Avalara recognizes the standard letter codes (A = Federal government, B = State/local government, C = Tribal government, D = Foreign diplomat, E = Charitable, F = Religious/educational, G = Resale, etc.).
Open the Company, click View all properties, search for Ava_EntityUseCode, and enter the appropriate letter. The next tax calculation will mark applicable line items as exempt.
Why this is the fallback, not the recommended path: Setting an entity use code tells Avalara "trust me, this customer is exempt" - Avalara will mark the transaction as exempt without ever checking whether a valid certificate is actually on file. That's faster to set up, but it leaves you exposed in an audit if you don't have the backing documentation. Whenever possible, upload the actual certificate in Avalara (Method 1) and let the tax engine do the verification.
The integration determines the ship-to address by checking, in order:
Ava_Deal Ship-To properties on the DealFor B2B job-site sales where each Deal ships to a different location, turn on Use Deal Ship-To in Sync Settings, then populate the five Ava_Deal Ship-To properties (Line 1, City, Region/State, Postal Code, Country) directly on each Deal.
To find these fields on a Deal, open the Deal record and click View all properties in the right sidebar (or click Actions → View all properties at the top), then search for Ava_Deal to see all five Ship-To fields.
When the deal-level toggle is on, the integration hard-fails if the Deal's ship-to fields are blank - it won't silently fall back to the company address. This is intentional: silent fallback would produce wrong tax on misconfigured Deals.
If you ship from more than one location, you can register each warehouse in Company Settings and select the right one per line item. Avalara uses the ship-from address to determine origin-based tax in 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 (e.g., TX01), name, and full address. In HubSpot, each line item will have an Ava_ShipFromLocation dropdown to pick the source warehouse. If no location is selected on a line item, the default company address is used.
If you don't see the Ava_ShipFromLocation column on the Line Items table, click Actions → Edit columns on the table, search for it, and add it to the visible columns.
If your business operates under multiple legal entities each with its own Avalara company code (e.g., a US subsidiary and an EU subsidiary), you can route Deals to the correct Avalara company based on a HubSpot Deal property.
In Sync Settings, scroll to the Entity Routes section. Pick the HubSpot Deal property the integration should read (e.g., a custom bc_entity property), then add a routing row for each entity value (e.g., "Acme USA Inc" → ACMEUSA). When a Deal calculates, the integration reads the property value off the Deal and sends the calculation to the matching Avalara company.
This is an advanced feature - most customers run on a single Avalara company code and can ignore this section. Contact avataxforhubspot@taxiom.com if you need help configuring it.
For special cases where you need to override the tax amount on a specific line item (negotiated tax, manually-calculated tax for a special jurisdiction, etc.), 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, this must happen on the Deal - overrides set on a downstream Quote, Invoice, or Subscription line won't take effect.
If you don't see the Ava_OverrideTaxValue column on the Line Items table, click Actions → Edit columns on the table, search for it, and add it to the visible columns. The same applies to Ava_LineUseCode and Ava_ShipFromLocation - any line-item-level Ava field needs to be added via Edit columns to be visible and editable.
Important: set the override on the actual source line item (e.g., the Test Product line), not on the auto-managed "Sales Tax" line. The Sales Tax line is created by the integration to display the total tax; overrides on it are ignored. To clear an override and return to Avalara's calculated value, just empty the cell.
Every record the integration touches gets an ava_tax_status property with one of three values:
The full audit trail lives in Errors Logs in the AvaTax portal. Every failed calculation logs the exception type, message, Deal/Quote/Invoice context, and timestamp.
The most common error categories:
Ava_TaxCode value that Avalara doesn't recognizeThe Admin page in the AvaTax portal sidebar is where you manage your account details and find your billing receipts.
If you create Quotes or Invoices programmatically outside of HubSpot - from a custom checkout, an ERP system, or your own product - the deal-centric flow described above doesn't apply. For those scenarios, we offer a Pre-Calc API as a paid add-on to the AvaTax for HubSpot integration.
You call our endpoint with the line items and ship-to address before generating your Invoice. We calculate tax through Avalara using your existing credentials and return the Sales Tax amount, shaped for inclusion in your Invoice payload.
If this fits your use case, email avataxforhubspot@taxiom.com with a short description of your setup and we'll send pricing, docs, and access details.
The Pre-Calc API is built for high-volume programmatic flows. If you only generate a handful of HubSpot-external Invoices, you can mirror the line items into a HubSpot Deal as a workaround, let the standard 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 the right transaction details to Avalara - what's being sold, where it's shipping to, who the buyer is. Avalara then applies all three rules above and tells us the tax amount. If you're seeing $0 tax when you expected a charge (or a tax 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 - including ones that result in zero tax - to properly track your nexus exposure across all states. Even if you're not currently registered to collect tax in a particular state, every transaction still counts toward whether you've crossed an economic-nexus threshold there. Leaving the Sales Tax line in place on every Deal gives you a single, uniform tax process: every Invoice is assessed the same way, with no manual decisions about whether to "include tax this time."
HubSpot's native tax fields on Quotes and Invoices are not accessible to third-party integrations - we weren't able to get the right access from HubSpot to write into them. To work around this, the integration creates a dedicated Sales Tax product as its own line item. That approach lets us both trigger the tax calculation and make sure the sales tax dollar amount rolls correctly into the Deal/Quote/Invoice total. The buyer sees a clean "Sales Tax" line on their Quote, Invoice, or Payment Link, and the math adds up correctly.
That $0 state is a visual signal that a recalculation is in progress. When you change a line item on the Deal's Line Items page, the integration clears the previous tax value, sends a fresh calculation to Avalara, and writes the new value back - usually within 5-10 seconds. You'll also see the ava_tax_status property cycle from "calculated" to "pending" and back to "calculated" during this window.
5-10 seconds for the typical case. The clock starts when HubSpot sends us the line-item change webhook and ends when the Sales Tax line is updated with the calculated amount. If you don't see the update after 30 seconds, check the Errors Logs in the AvaTax portal.
Two possible reasons: (1) the "Auto-calculate only for US-based Deals and Subscriptions" toggle is on in Sync Settings - the integration is intentionally skipping non-US Deals because you've told it Avalara isn't handling your international tax; or (2) the associated Company or Contact's country field is blank, so the integration cannot determine the destination and treats it as non-US. Check Sync Settings for the US-only toggle, and confirm the Company/Contact has a populated country.
Usually this happens when a HubSpot workflow populates the ship-to address a few seconds after Deal creation - by the time the workflow finishes, the integration has already tried (and failed) to calculate tax. Turn on Mute error notification emails in Sync Settings. Errors are still logged in the AvaTax portal for audit, but reps stop getting emails for transient errors that resolve on their own.
By default, the integration sends draft calculations as SalesOrder transactions, which are about 1/10 the cost of full SalesInvoice transactions and don't count toward your Avalara filing data. They appear as "Temporary" in your Avalara dashboard. Once the customer pays (or the Quote/Invoice transitions to a committed state), the integration upgrades the transaction to SalesInvoice and commits it for filing purposes. Adjust the Commit Interval in Sync Settings to control when commits happen.
Yes. Edit Tax Label in Sync Settings to whatever fits your market - "VAT", "GST", "Tax", etc. The label appears on customer-facing Quotes, Invoices, and Payment Links wherever the Sales Tax line is shown.
Once a HubSpot Invoice transitions from draft to "open" status (sent to the customer), HubSpot snapshot-locks the subtotal, billed amount, and tax total. There's no public HubSpot API to force a recompute on a sent Invoice. The integration can still write a new Sales Tax value, but HubSpot will continue to display the snapshot amount the buyer was originally shown. The cleanest workaround: void the Invoice, edit the source Deal's line items, and create a fresh Invoice from the updated Deal.
Yes - this is a known HubSpot API limitation, not a bug. Tax is calculated and applied to the first Invoice generated from a Subscription. Each subsequent recurring Invoice that HubSpot creates copies the same line items (including the Sales Tax line with the original value), so the tax stays constant across billing cycles. That's correct for stable Subscriptions, but if the customer's address, product taxability, or jurisdictional rates change mid-Subscription, the recurring Invoices will show stale tax. The recommended fix: create a new Deal, add the (updated) line items to that new Deal so the integration calculates fresh tax, then create a new Subscription from that new Deal. Editing the existing Subscription's line items does nothing - that path doesn't trigger a recalc - and editing the original source Deal's line items won't flow into the already-created Subscription either. We'll close this gap as soon as HubSpot exposes the API access we need.
If something isn't working, here's the order to check:
ava_tax_status property on the Deal/Quote/Invoice. If "failed", that points you at the issue.Ava_Deal Ship-To properties are populated).If you've checked all of the above and tax still isn't calculating, email avataxforhubspot@taxiom.com with the Deal/Quote/Invoice URL and a brief description of what you expected vs. what happened. We respond 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_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_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) |
Email avataxforhubspot@taxiom.com with your Deal URL and we'll get back to you the same day.
Watch the 10-minute walkthrough ↑