{"title":"Avalara AvaTax","slug":"avatax","url":"https://support.storeconnect.com/articles/avatax","url_markdown":"https://support.storeconnect.com/articles/avatax.md","subtitle":null,"summary":"Connect an Avalara AvaTax account for automated real-time tax calculation across 12,000+ US jurisdictions and 200+ countries, including credentials, fallback addresses, product tax codes, and advanced options.","type":"Help_Documentation","video_url":"","keywords":"Avalara, AvaTax, tax automation, automated tax, tax calculation, Avalara credentials, API key, API secret, company code, sandbox, production, freight tax code, block transactions, channel scoping, POS tax, fallback address, US jurisdictions, tax provider, real-time tax, tax codes","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"StoreConnect supports calculating taxes using your Avalara AvaTax account. Avalara AvaTax is a cloud-based solution automating transaction tax calculations and the tax filing process. Avalara provides real-time tax calculation using tax content from more than 12,000 US taxing jurisdictions and over 200 countries, ensuring your transaction tax is calculated based on the most current tax rules.\n\n## Create an Avalara account\n\nThis feature requires an Avalara account. [Sign up with Avalara](https://www.avalara.com/us/en/get-started.html) if you don’t already have an account.\n\n## Connect StoreConnect to AvaTax\n\n:::note\nA Tax Provider applies only to the stores that point at it. The link lives on the\n**Store** record, in its **Tax Provider** field, not on the Tax Provider itself.\nCreate one Tax Provider per Avalara account, then set that field on each store that\nshould use it. A store with no **Tax Provider** selected calculates no AvaTax on any\nchannel, even when an active Tax Provider exists in the org.\n:::\n\nTo connect StoreConnect to your Avalara account, create a Tax Provider record:\n\n1.  Search for the record type **Tax Providers** and select **New**.\n2.  Choose **Avalara** from the **Provider** list.\n3.  Configure the Tax Provider details as follows:\n    -   **Active**: when checked, Avalara will be used to calculate taxes. Uncheck to disable Avalara and use the built-in StoreConnect tax calculation.\n    -   **Company Code**: this is an Avalara code to identify the Company you are configuring. If not supplied, uses the default code set in Avalara.\n    -   **Default Freight Tax Code**: the AvaTax System Tax Code applied to the shipping line on every order. Refer to the [AvaTax tax code catalog](http://taxcode.avatax.avalara.com) for the correct code.\n    -   **Block Transactions When Offline**: If AvaTax is unavailable, should transactions be blocked? If unchecked, transactions will be allowed and taxes will fall back to your store's local tax configuration (or zero if no local taxes are set up). If checked, transactions will be blocked and an error message will be displayed to the user.\n    -   **Block Transactions Markdown**: This is the error message displayed to the user when transactions are blocked due to AvaTax being unavailable.\n    -   **Channels**: select which sales channels this tax provider applies to — **Web**, **POS**, or both. Channels is required. A provider set to Web only will not calculate taxes on POS transactions (and vice versa). Select both if you want AvaTax to apply to all channels.\n4.  Enter the **API Info**:\n      -   **API Mode**: controls which AvaTax endpoint is used. Enter `production` (exact value, case-sensitive) to connect to the live AvaTax service. Enter `sandbox` or leave blank to use the AvaTax sandbox endpoint for testing.\n      -   **API Key**: this is your Avalara Account Number\n      -   **API Secret**: this is the License Key for your Avalara account\n\n5.  Enter a fallback address. This is used if a product has no stock location, a product has no stock locations matching the tax provider's country, a product stock location address is incomplete.\n6.  Add any advanced configuration options in the **Configuration Options** field. (See details below)\n7.  Save the record.\n\nThen point each store at it:\n\n1.  Open the **Store** record.\n2.  Set **Tax Provider** to the record you just created.\n3.  Save the store.\n\nRepeat for every store that should use this provider. This step is what activates\nAvaTax; creating the Tax Provider on its own has no effect on any store.\n\n:::warning\nA store with no **Tax Provider** selected calculates no AvaTax at all, on web and POS\nalike, and gives no error. Unless the products are set up to use StoreConnect's\nbuilt-in tax calculation, orders simply complete with a tax amount of zero. If tax is\nmissing everywhere, check this field on the store before investigating credentials or\ntax codes.\n:::\n\n:::note\nIf you ship from multiple locations, you do not need a separate Tax Provider record\nper location. AvaTax determines the ship-from address for each line item from that\nproduct's own **Stock Location** record — which has its own address — so a single\nTax Provider already handles multiple shipping locations correctly. The fallback\naddress entered in step 5 above is only used when a product's Stock Location can't\nsupply a usable address; it is not a way to configure per-location tax behavior.\n:::\n\n### Shipping tax\n\nShipping tax is controlled by the Tax Provider's **Default Freight Tax Code**, not by the **Tax Code** field on the StoreConnect Shipping product record. Any value set on the Shipping product's Tax Code is ignored.\n\n### Advanced configuration options\n\nThese options only need to be set if you intend to override the default value. They should be on their own line and should follow a YAML format: “{option\\_name}: {option value}”. Here are the available options:\n\n| Option Name         | Expected Value | Default Value | Setting Effect                                                                                              |\n|---------------------|----------------|---------------|-------------------------------------------------------------------------------------------------------------|\n| commit_transactions | true or false  | false         | If true commits all transactions in Avalara. Not applicable when disable_invoices is true                   |\n| disable_invoices    | true or false  | false         | If true, does not create transactions in Avalara for invoices                                               |\n| log_requests        | true or false  | false         | If true, turns logging on. All API requests and responses will be logged in the Tax Provider Log object     |\n| log_limit           | integer        | 1000          | Sets the number of rows to keep in the log. When the log reaches the limit, the oldest rows will be deleted |\n\n### Test and sandbox credentials\n\nUse `sandbox` (or leave the field blank) while testing, then change the value to `production` when you are ready to go live. The value `production` must be entered exactly as shown — it is case-sensitive.\n\n## Assign a tax exempt category on the Account record\n\nUse **Tax Entity Code** on the Account record to assign an Avalara tax exempt category to an existing customer. Select one of the options from the picklist.\n\n## Assign a tax code on the Product record\n\nUse **Tax Code** on a Product record to assign an AvaTax System Tax Code to a Product. Any tax code you assign will be passed through to AvaTax for tax calculation. If you do not assign a tax code, AvaTax’s default tax code will be used. To see a listing of all available AvaTax System tax codes, visit [taxcode.avatax.avalara.com](http://taxcode.avatax.avalara.com).\n\n## Set the tax method on a Price Book\n\nWhen Avalara calculates tax, it needs to know whether your prices already include tax or whether tax should be added on top. This is controlled by the **Tax Method** field on a Price Book or Price Book Entry.\n\n-   **Inclusive** — your prices already include tax; Avalara will back-calculate the tax portion.\n-   **Exclusive** — your prices do not include tax; Avalara will add tax on top.\n\nIf neither the Price Book Entry nor the Price Book has a Tax Method set, Avalara treats prices as exclusive by default (tax added on top). For stores that display or charge tax-inclusive prices, leaving this field blank will cause incorrect order totals.\n\nThe resolution order is:\n\n1.  Tax Method on the **Price Book Entry** (most specific — overrides the Price Book).\n2.  Tax Method on the **Price Book** (applies to all entries that don't have their own override).\n3.  If neither is set, prices are treated as tax-exclusive.\n\n**Note:** The Tax Zone field on a Price Book is not used by Avalara. Avalara determines tax jurisdiction from the ship-from and ship-to addresses on the order, not from zones. Leave Tax Zone blank when using Avalara as your tax provider.\n\n## Set a product code on the Shipping Product record\n\nStoreConnect has a dedicated 'shipping' product that is assigned to Shipping line items - `SHIP001`. This is the product code sent to AvaTax to identify the line; it is separate from the tax code applied to the shipping line.\n\n## Tax Provider information is not available in Liquid\n\nThere is no Liquid object for Tax Provider, and the `Tax` object (available via\n`cart.taxes` and `order.taxes`) does not reference which Tax Provider produced it —\nit only exposes `name`, `rate`, and `zone`. A theme cannot detect which Tax Provider\ncalculated a cart or order's tax, or distinguish between multiple Tax Providers if\nmore than one exists in the org.\n\n## Decide what happens when AvaTax is unreachable\n\nAvaTax is a live call to an external service, so a register or storefront that cannot\nreach it has to do something. **Block Transactions When Offline** decides which, and\nthe two settings suit different businesses.\n\n| Setting | What happens when AvaTax cannot be reached |\n|---------|--------------------------------------------|\n| Unchecked | The sale completes. Tax falls back to the store's local tax configuration, or to **zero** if no local taxes are set up. |\n| Checked | The sale is blocked and **Block Transactions Markdown** is shown to the operator or customer. |\n\nNeither is safer in general, so choose against your own risk:\n\n- **Unchecked** keeps you trading through an outage, but you may collect no tax on\n  those sales and have to correct them afterwards. Set up local taxes as a fallback if\n  you take this route, otherwise the fallback really is zero.\n- **Checked** guarantees you never undercharge tax, at the cost of stopping sales\n  during an outage. On a POS register this means staff cannot complete a transaction\n  in front of a waiting customer.\n\n:::note\nThis matters more on POS than on the web. A register is expected to keep working when\nthe connection drops, and most other POS payment methods do. AvaTax is one of the few\nthings that genuinely cannot work offline, because the calculation happens at Avalara.\n:::\n\n### Test both behaviors before you go live\n\nTesting this is worth doing deliberately, because the failure only appears when the\nconnection fails.\n\n1.  Open the **Tax Provider** record and note the current **Block Transactions When\n    Offline** setting.\n2.  On the device you want to test, disconnect it from the network. In a browser, the\n    network throttling option in the developer tools has an **Offline** mode, which\n    affects only that tab.\n3.  Build a cart and go to payment.\n4.  With the setting **unchecked**, confirm the sale completes and check what tax was\n    applied. Zero tax here means you have no local tax fallback configured.\n5.  With the setting **checked**, confirm the sale is blocked and that your **Block\n    Transactions Markdown** message is the one staff actually see. Write that message\n    for the person reading it: say what to do next, not just that something failed.\n6.  Reconnect and confirm normal calculation resumes.\n\n## Test the connection\n\nOnce you have configured your store to use Avalara, you can test the connection to ensure everything is working properly. Use the **Test** button in the **Connectivity** panel on the Tax Provider record page. If the connection is successful, you will see a message indicating the connection was successful. If the connection is not successful, you will see an error message indicating the problem.\n\n## Troubleshooting the tax provider\n\nAvaTax won't work without these set in the provider record:\n\n- API Key and API Secret — authentication, no fallback\n- API Mode — determines the endpoint called `sandbox` or `production`. These have to be entered exactly to work as intended.\n- Active checkbox — AvaTax is bypassed entirely if unchecked\n\n### Shipping line is still being taxed after setting a Tax Code on the StoreConnect Shipping product\n\nShipping tax is sourced from the **Default Freight Tax Code** field on the Tax Provider record, not the **Tax Code** field on the StoreConnect Shipping product. The Tax Code on the Shipping product is not consulted for the shipping line. To change shipping tax behavior; for example, to make shipping non-taxable, or to apply a specific freight tax code, set the appropriate AvaTax code on the Tax Provider's **Default Freight Tax Code** field, then re-test checkout."}