Avalara AvaTax

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.

Create an Avalara account

This feature requires an Avalara account. Sign up with Avalara if you don’t already have an account.

Connect StoreConnect to AvaTax

:::note A Tax Provider applies only to the stores that point at it. The link lives on the Store record, in its Tax Provider field, not on the Tax Provider itself. Create one Tax Provider per Avalara account, then set that field on each store that should use it. A store with no Tax Provider selected calculates no AvaTax on any channel, even when an active Tax Provider exists in the org. :::

To connect StoreConnect to your Avalara account, create a Tax Provider record:

1. Search for the record type Tax Providers and select New.
2. Choose Avalara from the Provider list.
3. Configure the Tax Provider details as follows:
   • Active: when checked, Avalara will be used to calculate taxes. Uncheck to disable Avalara and use the built-in StoreConnect tax calculation.
   • Company Code: this is an Avalara code to identify the Company you are configuring. If not supplied, uses the default code set in Avalara.
   • Default Freight Tax Code: the AvaTax System Tax Code applied to the shipping line on every order. Refer to the AvaTax tax code catalog for the correct code.
   • 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.
   • Block Transactions Markdown: This is the error message displayed to the user when transactions are blocked due to AvaTax being unavailable.
   • 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.
4. Enter the API Info:
   • 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.
   • API Key: this is your Avalara Account Number
   • API Secret: this is the License Key for your Avalara account
5. 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.
6. Add any advanced configuration options in the Configuration Options field. (See details below)
7. Save the record.

Then point each store at it:

1. Open the Store record.
2. Set Tax Provider to the record you just created.
3. Save the store.

Repeat for every store that should use this provider. This step is what activates AvaTax; creating the Tax Provider on its own has no effect on any store.

:::warning A store with no Tax Provider selected calculates no AvaTax at all, on web and POS alike, and gives no error. Unless the products are set up to use StoreConnect’s built-in tax calculation, orders simply complete with a tax amount of zero. If tax is missing everywhere, check this field on the store before investigating credentials or tax codes. :::

:::note If you ship from multiple locations, you do not need a separate Tax Provider record per location. AvaTax determines the ship-from address for each line item from that product’s own Stock Location record — which has its own address — so a single Tax Provider already handles multiple shipping locations correctly. The fallback address entered in step 5 above is only used when a product’s Stock Location can’t supply a usable address; it is not a way to configure per-location tax behavior. :::

:::warning Use a real, deliverable street address for the fallback address. If Avalara cannot match the street it still returns a rate, but adds a message such as “An exact street name match could not be found”, so the tax looks calculated while being derived from a partially-resolved location. To confirm the address resolved, set log_requests: true in Configuration Options, place a test order, then check the response in the Tax Provider Log (see Read the Tax Provider Log). :::

How AvaTax calculates on POS

For a POS sale, StoreConnect sends a shipFrom and a shipTo address on each line of the transaction, and the two are taken from different records.

shipFrom comes from the Tax Provider, not from the outlet. It is built from the ship-from fields on the Tax Provider record. One Tax Provider serves every store and outlet that uses it, so unless you create more than one, every register in the org sends the same origin address.

shipTo is resolved for each line, in this order:

1. The delivery address on the line, when that item is being shipped to a customer.
2. The address of the outlet fulfilling the line, when the line names one.
3. The register’s own outlet address.

A sale carried out of the shop falls to the third case, so both addresses come from your configuration rather than from the customer. An item sent out on a delivery is taxed to the delivery address instead, and an item fulfilled by another outlet is taxed to that outlet, so one transaction can carry a different shipTo on each line.

Two addresses therefore decide the rate at the register, and neither fails loudly when it is wrong. A wrong, incomplete, or placeholder address produces a plausible rate for the wrong jurisdiction rather than an error. Before going live with AvaTax on POS, check the ship-from fields on the Tax Provider, and check Address Line 1, City, State/Province, Zip/Postal Code, and Country on every Outlet record. See Create a store outlet.

The two are not equally forgiving about the country. The Tax Provider’s country is passed to Avalara as you enter it, and a two-letter code, a three-letter code, or a full country name are all accepted. An outlet’s country is resolved to its two-letter code first, so an outlet whose country cannot be resolved sends no country at all.

When no customer is attached to the sale, the request is sent with a customerCode of POS_GUEST. Attach a customer if you need the Account’s Tax Entity Code exemption to apply.

Shipping tax

Shipping 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.

Advanced configuration options

These 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:

Option Name	Expected Value	Default Value	Setting Effect
commit_transactions	true or false	false	If true commits all transactions in Avalara. Not applicable when disable_invoices is true
disable_invoices	true or false	false	If true, does not create transactions in Avalara for invoices
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
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

Read the Tax Provider Log

Logging is off by default. Set log_requests: true in Configuration Options on the Tax Provider, then place a test order. Every AvaTax call is written to the Tax Provider Log object as a request/response pair. This is the only place that distinguishes “AvaTax was never called” from “AvaTax was called and returned zero”, two very different problems that look identical on the order.

:::warning Turn logging on before you use the log to diagnose anything. With log_requests left at its default of false, nothing is written for any sale, so an empty log tells you nothing about whether AvaTax was called.

The log is also capped. When it reaches log_limit rows, the oldest row is deleted to make room for the newest, so an older sale can age out of the log entirely. Place a fresh test order and read that, rather than looking for a transaction from last week. :::

A completed sale normally produces two log rows, not one:

Order	type	status	When
First	SalesOrder	Temporary	The quote, during checkout
Second	SalesInvoice	Saved	On completion, only when commit_transactions: true

Read a log row like this:

• The request shows what was sent: each line’s taxCode, itemCode, amount, taxIncluded, and the shipFrom and shipTo addresses actually used. This is where a wrong tax code or a wrong outlet address becomes visible.
• The response gives totalTax and, per line, tax, isItemTaxable and a details array breaking the rate down by jurisdiction. For example, an Ohio sale showing a state rate of 0.0575 plus a county rate of 0.015. Take the applicable rate from details rather than assuming a figure for the state or county.

Once logging is on and you have placed a test order, diagnose from the log as follows:

What you see	What it means
No log rows for the sale	AvaTax was never invoked. The problem is upstream of the call: Active, Channels, or the store’s Tax Provider link, not your Avalara credentials.
A log row with an authentication or company error	Credentials or Company Code are wrong. Fix from the error text.
A log row, but the order still shows zero tax	Avalara returned zero. Usually a tax code, address, or nexus issue in the Avalara company.

Test and sandbox credentials

Use 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.

Assign a tax exempt category on the Account record

Use 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.

Assign a tax code on the Product record

Use 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.

Voucher products need their own tax code

Gift cards are sold in StoreConnect as voucher products. See Create a voucher product.

Gift cards are normally taxed when they are redeemed, not when they are sold. If you leave Tax Code blank on a voucher product, Avalara applies its default general goods code P0000000 (tangible personal property) and taxes the card at the point of sale, which is usually wrong.

Set Tax Code on the voucher product to the code that matches how the card is delivered:

Voucher product	Avalara code	Description
Physical gift card	PG050000	Gift certificates
E-gift card	DG020000	Electronically-delivered gift cards

Prefer these specific codes over a blanket non-taxable code. They let Avalara apply the correct rule for each jurisdiction, rather than suppressing tax everywhere regardless of local law.

Set the tax method on a Price Book

When 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.

• Inclusive — your prices already include tax; Avalara will back-calculate the tax portion.
• Exclusive — your prices do not include tax; Avalara will add tax on top.

If 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.

The resolution order is:

1. Tax Method on the Price Book Entry (most specific — overrides the Price Book).
2. Tax Method on the Price Book (applies to all entries that don’t have their own override).
3. If neither is set, prices are treated as tax-exclusive.

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.

Set a product code on the Shipping Product record

StoreConnect 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.

Tax Provider information is not available in Liquid

There is no Liquid object for Tax Provider, and the Tax object (available via cart.taxes and order.taxes) does not reference which Tax Provider produced it — it only exposes name, rate, and zone. A theme cannot detect which Tax Provider calculated a cart or order’s tax, or distinguish between multiple Tax Providers if more than one exists in the org.

Decide what happens when AvaTax is unreachable

AvaTax is a live call to an external service, so a register or storefront that cannot reach it has to do something. Block Transactions When Offline decides which, and the two settings suit different businesses.

Setting	What happens when AvaTax cannot be reached
Unchecked	The sale completes. Tax falls back to the store’s local tax configuration, or to zero if no local taxes are set up.
Checked	The sale is blocked and Block Transactions Markdown is shown to the operator or customer.

Neither is safer in general, so choose against your own risk:

• Unchecked keeps you trading through an outage, but you may collect no tax on those sales and have to correct them afterwards. Set up local taxes as a fallback if you take this route, otherwise the fallback really is zero.
• Checked guarantees you never undercharge tax, at the cost of stopping sales during an outage. On a POS register this means staff cannot complete a transaction in front of a waiting customer.

:::note This matters more on POS than on the web. A register is expected to keep working when the connection drops, and most other POS payment methods do. AvaTax is one of the few things that genuinely cannot work offline, because the calculation happens at Avalara. :::

Test both behaviors before you go live

Testing this is worth doing deliberately, because the failure only appears when the connection fails.

1. Open the Tax Provider record and note the current Block Transactions When Offline setting.
2. On the device you want to test, disconnect it from the network. In a browser, the network throttling option in the developer tools has an Offline mode, which affects only that tab.
3. Build a cart and go to payment.
4. With the setting unchecked, confirm the sale completes and check what tax was applied. Zero tax here means you have no local tax fallback configured.
5. With the setting checked, confirm the sale is blocked and that your Block Transactions Markdown message is the one staff actually see. Write that message for the person reading it: say what to do next, not just that something failed.
6. Reconnect and confirm normal calculation resumes.

Test the connection

Once 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.

Troubleshooting the tax provider

AvaTax won’t work without these set in the provider record:

• API Key and API Secret — authentication, no fallback
• API Mode — determines the endpoint called sandbox or production. These have to be entered exactly to work as intended.
• Active checkbox — AvaTax is bypassed entirely if unchecked

Tax calculates on the web store but POS orders show zero

If web checkout produces tax and the same products sold at a register produce none, confirm the following in order:

1. Open the Tax Provider record and confirm Channels includes POS. A provider set to Web only calculates no tax on POS transactions.
2. Set log_requests: true in Configuration Options, then put a test sale through the register and check the Tax Provider Log. No log rows for that sale means AvaTax was never called, which rules out credentials and tax codes as the cause.
3. Check the outlet’s address. Tax at the register is calculated from it, so a wrong or incomplete address produces the wrong rate. See How AvaTax calculates on POS.
4. Check your website version. POS tax calculation depends on the website release rather than on Salesforce configuration, so a store on an older website version can have a completely correct Tax Provider and still calculate no tax on POS. If the configuration checks out and the log stays empty with logging on, contact StoreConnect support to confirm your store is on a version that supports it.

Shipping line is still being taxed after setting a Tax Code on the StoreConnect Shipping product

Shipping 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.