Avalara AvaTax

The Avalara AvaTax app makes Avalara AvaTax the tax service for your Swell store. Once you turn it on, Swell asks AvaTax for the taxes on carts, orders and subscriptions instead of using its own tax rules. AvaTax works out the tax for each item and for shipping from the customer's address, your store locations and the tax codes you use.

The app also records paid orders and invoices in AvaTax as committed sales, so they appear in your AvaTax reports and returns. Changes and returns update the AvaTax document, and canceling the order voids it. Customers can be marked tax-exempt on their customer page.

All of this runs only while Avalara AvaTax is turned on in Settings > Taxes. Until then, Swell doesn't ask the app for taxes, and the app records nothing.

Install Avalara AvaTax from the Swell App Store, and set it up in your test environment before the live one.

If Swell's built-in Avalara AvaTax integration is on when you install the app, Swell shows Avalara AvaTax may have conflicts. Click Disable conflicting integration to turn off the built-in integration and install the app. Ignore conflict installs the app and leaves the built-in integration on. Cancel stops the install.

The app doesn't read the built-in integration's credentials, so you enter them again in step 2. Disable conflicting integration takes effect right away: until you turn AvaTax on in step 4, the store uses Swell's own tax rules. To change over without that gap, click Ignore conflict, finish step 4, then go to Integrations, open Avalara AvaTax and click Deactivate. Don't leave both on. See Documents are overwritten or recorded twice under Troubleshooting.

While AvaTax is on, Swell asks the app for taxes when a cart, order or subscription is saved with a change that can affect them: items or quantities, a coupon or promotion, the country, state or zip code of an address, or the shipping charge. For carts and orders, it asks again when the order is submitted. AvaTax calculates the taxes and keeps no document of the calculation.

AvaTax needs an address: a shipping or billing address with a zip code, or with a street, city and state. Until a record has one, the app returns no tax and doesn't call AvaTax, so a cart shows no tax until the customer enters an address. AvaTax gets:

Each item and the shipping get their own tax. The record shows one tax line named after AvaTax's tax type, such as Sales tax.

For a subscription, the plan product is sent as one more line, except during a trial. Swell calculates a subscription's taxes when the subscription changes, not at each renewal, and its invoices and renewal orders take the taxes saved on the subscription.

Each line goes to AvaTax with a tax code. To look up codes, use Avalara's tax code search.

The Tax code field shows on the product page only while Swell's built-in AvaTax or TaxJar integration is connected, and on shipping services in Settings > Shipping only while the built-in AvaTax integration is connected. With the app alone, those fields are hidden. Codes already saved on products and shipping services stay there, and the app uses them.

When AvaTax refuses a calculation, can't be reached or doesn't answer in time, or a call to Swell fails or takes too long, the app logs AvaTax: taxes not calculated: … with the reason. Reject when AvaTax fails, on the Tax calculation tab, decides what happens next:

Swell waits 10 seconds for the app, and the app gives itself 8 seconds from when it starts. If loading your store locations, the customer and the products from Swell uses up the 8 seconds, the calculation fails with "Calculating took too long." AvaTax then gets 6 seconds, or the time left if that's less, and a slower answer fails with "AvaTax didn't answer in time." The setting applies to both. If the function itself fails, or doesn't answer within 10 seconds, Swell saves the change without tax, whether the setting is on or off. If the account ID, license key or company code is empty, the app logs AvaTax: missing … in app settings and returns no tax, without an error.

An order placed without tax is still recorded when it's paid. AvaTax calculates its tax at that point, so the document shows tax you didn't charge.

With Record paid orders in AvaTax on, each order paid in full and each paid invoice is saved in AvaTax as a committed sales invoice, which AvaTax needs for its returns and reports. Unpaid orders aren't sent, and neither are invoices created from an order, because the order already records that sale. Each document has:

AvaTax calculates the tax again when it records the sale. The recorded tax can differ from what the customer paid, for example if a rate changed in between.

Turn the setting off if another system records your sales. Taxes are still calculated, and nothing is recorded, updated or voided in AvaTax.

Orders paid before you turned AvaTax on aren't sent, unless one of them changes later.

AvaTax can refuse to change a document, for example when it's locked after filing. The app logs the error and doesn't try again, so make the change in AvaTax.

To mark a customer as tax-exempt, open the customer in Customers, open the AvaTax tab, set Entity use code and Exemption number, and click Save changes. Customers who check out as guests have a customer record too, so the same tab works for them.

Settings are in Apps > Avalara AvaTax > Settings and are saved separately for each environment.

Environment, Account ID, License key and Company code are at the top. The other settings are on the Tax calculation and Recording sales tabs.

Test connection shows its result in a message, and a rejected change returns its error to whoever made it. The app also logs its errors. In the Swell dashboard, the logs are under Developer > Console > Logs.

Swell's built-in Avalara AvaTax integration is on, and Swell lists it when you install or enable the app. Disable conflicting integration turns it off and keeps its settings, so you can turn it on again from Integrations. Ignore conflict leaves it on. Turning on the integration while the app is installed shows Avalara AvaTax may conflict with apps you already use.

The built-in integration and the app are both on. While Avalara AvaTax is on in Settings > Taxes, Swell skips the integration's calculation, so the app sets the taxes. The integration still records: on order and invoice changes, payments and refunds, it sends the sale to AvaTax with its own credentials and the same document code.

In the same AvaTax company, each write replaces the other, and the integration's version has no entity use code or exemption number, so an exempt sale can come back taxable. In another company or account, the sale is recorded in both. To stop this, go to Integrations, open Avalara AvaTax and click Deactivate, which also clears the integration's settings.

While the app isn't turned on in Settings > Taxes, the integration does everything and the app records nothing.

Check that Avalara AvaTax is on in Settings > Taxes and that you clicked Save changes. Until then, Swell's own tax rules apply. Then check that the Account ID, License key and Company code are saved, because the app returns no tax while one is missing, and that the address has a zip code, or a street, city and state.

If the app is calling AvaTax and the tax is still zero, check the company's Settings > Where you collect tax in AvaTax, the tax codes, and the customer's Entity use code. If Reject when AvaTax fails is off, look for AvaTax: taxes not calculated: … in the logs.

The field shows only while a built-in tax integration is connected. See Product and shipping tax codes above. To set codes on products, use Edit Products on the Products page.

The calculation failed while Reject when AvaTax fails is on, and the reason follows the message. "Calculating took too long. …" means the app's 8 seconds ran out while it loaded the record from Swell, before it asked AvaTax. The log line AvaTax: taxes not calculated: … adds AvaTax's error code and the refused call, such as POST /transactions/createoradjust.

A required setting is empty, and the message names it. Fill it in, click Save settings, and test again.

This log line means the store is using the app with a required setting empty, so no tax is calculated and nothing is recorded. Fill in the setting and click Save settings.

Copy the account ID again from Settings > License and API keys in AvaTax, and check the license key, including whether a newer key has replaced it. Check that Environment matches the account: sandbox accounts work only with Sandbox, and production accounts only with Production.

The credentials work, but the Company code doesn't match a company in this AvaTax account. Copy it from Settings > Manage companies in AvaTax. Sandbox and production accounts have their own companies.

Activate the company in AvaTax, or enter the code of an active one.

AvaTax answered 403. Check that the account has access to this company and to AvaTax.

The app couldn't connect to AvaTax. "AvaTax didn't answer in time. …", "AvaTax is limiting requests right now. …" and "AvaTax is not responding right now. …" are the same kind of error, for a slow AvaTax, rate limits and AvaTax server errors. Try again in a few minutes. Swell runs the function again for sales it couldn't record.

Something other than an AvaTax response failed, such as a call to Swell, and the reason follows. Try again. If it keeps happening, send the reason to support@swell.is.

AvaTax refused the transaction, and the message gives its status, error code and reason, such as InvalidAddress. Correct what it names, such as the address or a tax code.

Check that the order is paid in full, that Record paid orders in AvaTax is on, that Avalara AvaTax is on in Settings > Taxes, and that you're looking in the AvaTax account and company the app is connected to. Search Transactions > Transactions for the order number, or I- and the number for an invoice. If it still isn't there, look for a log line below.

AvaTax refused the sale, and the reason follows. For invoices, the line starts with AvaTax: invoices. This error isn't tried again. Fix the cause, then change the order or record it in AvaTax yourself.

The paid order has no usable customer address, and your store location has none either. Add an address to the order, or add your store location under Settings > Products.

Check that the customer's AvaTax tab was saved with an entity use code, because an exemption number alone isn't sent. Then change the cart so its taxes are calculated again. AvaTax applies an entity use code only where the reason applies. For a certificate saved in Avalara, check that its customer ID is the customer's email in lowercase.

Swell turned off the function after about 4 days of failures. Fix the cause, such as an AvaTax outage or changed credentials, and reinstall the app to turn it back on.

Uninstalling the app removes its functions and its settings, including the license key, the AvaTax tab on customers and the Test connection action, and removes Avalara AvaTax from Settings > Taxes. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

Swell clears the app as the tax service, and the store falls back to its own tax rules in Settings > Taxes. If no rule applies to an order, it's charged no tax. If the built-in integration is on, it calculates the taxes again. So in a live store, add your rules or connect another tax service first.

Documents, companies and certificates stay in AvaTax. The taxes already on your orders, subscriptions and invoices stay as they are, and customers keep their entity use codes and exemption numbers, which come back if you reinstall the app. After uninstalling, changes and cancellations no longer reach AvaTax, so void or adjust those documents in AvaTax.

To stop tax calculation without uninstalling, turn off Avalara AvaTax in Settings > Taxes and click Save changes. This also stops recording. To stop only recording, turn off Record paid orders in AvaTax. Disable app also clears the app as the tax service, so after Enable app, turn it on again in Settings > Taxes.

The app stores entity_use_code and exemption_number on accounts under $app.avatax. Calls go to the AvaTax REST API v2 at https://sandbox-rest.avatax.com/api/v2 or https://rest.avatax.com/api/v2, with basic auth and X-Avalara-Client: Swell; 1.0.0; REST; v2; Swell. A 2xx response with an error object is treated as status 400.

Swell runs the hook only for the extension selected in /settings/taxes, through extension_app_id and extension_config_id. Invoices don't run the hook: they copy the taxes of their subscription or order. The hook gets the change with the saved record in $record and merges them. It skips records with taxes_fixed, no usable address, or no items, plan and shipping service. Otherwise it reads /settings/shipments/locations, /settings/taxes, the account and the products, and sends POST /transactions/createoradjust with type: SalesOrder, commit: false, no code and today's date. AvaTax doesn't save SalesOrder documents, so carts and unpaid orders leave nothing in AvaTax.

The hook returns items[].taxes, shipment_tax, one taxes entry with the id avatax, and product_taxes for a subscription's plan. The name is summary[0].taxType plus tax, and the amount is the tax of the items and shipping. On failure it throws req.reject('avatax_failed', …, { status: 422 }) if block_on_failure is on. The hook has a deadline 8 seconds after it starts. It stops waiting for the locations, tax settings, account and products at the deadline, and aborts the AvaTax call after 6 seconds or at the deadline, whichever comes first. Both count as failures. Other AvaTax calls are aborted after 6 seconds. A hook that gives no answer fails open, and hooks get Swell's default 10 seconds.

Each item is a line with quantity_total, or quantity, and price_total minus discount_total, the SKU as itemCode (50 characters) and the name as description (2096 characters). Returned units are a second line with quantity_returned and the negative of return_price_total minus return_discount_total. The shipping line has the amount shipment_total, and an itemCode of the service ID in capitals, with _ as -, ending in -SHIPPING. A restocking fee is a line with the amount of return_credit_total as a negative, itemCode Restock fee and taxCode OR040000. Lines get taxIncluded from item_tax_included, tax_included or shipment_tax_included.

Lines use shipFrom and shipTo, or singleLocation with the customer's address when there's no usable ship-from address, or with the ship-from location when a paid record has no customer address. customerCode is the lowercased email, else the account ID, else guest. entityUseCode is sent when it's set, and exemptionNo only together with it.

*.updated events are handled only when $event.data has paid, canceled, void, items, shipping, billing, shipment_total, shipment_rating, return_credit_total, account_id, currency or taxes_fixed. The function also returns early when record_sales is off, a credential is missing, or the app isn't the selected tax service. It then reloads the record with items.product and account, plus subscription for invoices, and skips invoices created from an order.

A paid record is sent to the same endpoint with type: SalesInvoice, commit: true, code and purchaseOrderNo set to the document code, and date set to date_created. createoradjust updates the document when the code exists, so repeated events and retries are idempotent. Canceled orders and voided invoices call POST /companies/{company}/transactions/{code}/void?documentType=SalesInvoice with { "code": "DocVoided" }, and EntityNotFoundError and TransactionAlreadyCancelled count as done.

Network errors, timeouts, 429 and 5xx responses are rethrown so the platform retries the model event. Other AvaTax errors are logged with console.error and the function succeeds. Test connection calls GET /utilities/ping, checks authenticated, then calls GET /companies?$filter=companyCode eq '<code>' and checks isActive. Its errors are SwellErrors with status 400.

Swell builds and maintains the Avalara AvaTax app. For help with the app, email support@swell.is. For questions about your AvaTax account, nexus or filing, contact Avalara.