How Commerce AvaTax calculates US sales tax in your store
A Drupal Commerce store that sells into the United States has to charge the right sales tax at checkout, and the amount depends on where the order ships. Commerce AvaTax is a contributed module from Drupal.org that sends order data to the AvaTax service while the customer is checking out, receives the calculated tax back and applies it to the order. The store keeps control of the parts that matter for compliance: its tax configuration, the product tax codes assigned to each item, and the order records that show what was charged and why. The module does the calculation, but the store still decides which products are taxable, which tax codes they carry and what the checkout shows.
Before scoping, confirm three things on the module's Drupal.org project page and against your AvaTax account. First, check which Drupal and Commerce versions the current release supports, because a module release that does not match your core and Commerce versions will block the upgrade path. Second, list the configuration keys and settings the module expects, including how company codes, credentials and sandbox or production endpoints are set, and record where secrets will be stored. Third, confirm whether address validation is included in the module or requires a separate AvaTax feature and subscription on your account. Each of these answers changes the build and the recurring cost, so get them in writing from your AvaTax account owner before the statement of work is agreed.
Calculation errors usually come from data rather than from the calculation itself. A product with the wrong tax code, a shipping charge treated as taxable when your jurisdiction says otherwise, or a customer address that fails validation will produce a tax amount that looks correct in the cart and is wrong on the return. Plan a test matrix that covers your ship-to states, taxable and exempt products, discounts, shipping and refunds, and keep a record of each test order alongside the AvaTax transaction it produced. Whether you need that evidence for an auditor or simply for your own tax team, the order records in your store are the starting point.
What you need in place before configuring AvaTax
Most delays in an AvaTax project come from missing access, unclear ownership or an untested environment rather than from the tax logic itself. The cards below list what to confirm before configuration begins, who confirms each item and where to look for the authoritative details.
Supported Drupal and Commerce versions
Confirm that your Drupal core version is one the Drupal core release schedule still supports, and that the Commerce AvaTax module release you plan to use declares compatibility with that core and with your installed Drupal Commerce version. Drupal 10 reaches end of life on December 9, 2026, so a site that stays on it will need an upgrade plan regardless of tax work. Your Drupal lead or the module's compatibility notes on Drupal.org should be the source for this check.
AvaTax account and credentials
Confirm that your organization holds an active AvaTax account with a company code, and that the account credentials were issued by the vendor to the people who will manage them. Ask who holds the account owner role and who can rotate keys. DeployOpen does not hold or provision these credentials, so the account must be in your name or your finance team's name before the Drupal site is connected.
Outbound HTTPS from the web tier
Confirm with your network or cloud team that every web and cron node can reach the AvaTax API endpoint over outbound HTTPS, including through any egress proxy, firewall or allowlist. Check that the outbound rule applies to the staging environment as well. Tax calculation runs during checkout, so a blocked route shows up as failed orders or fallback behavior, not as a clear error page.
Staging copy of products and tax categories
Confirm that a staging environment holds a recent copy of production products, variations, tax categories and store addresses. Tax results depend on product tax codes and on the origin and destination addresses, so a staging site with placeholder products will not show the behavior you need to test. Ask your Drupal lead who refreshes the copy and how personal customer data is removed from it.
A named owner for tax settings
Confirm that one person in finance or tax, along with a technical deputy, owns the tax configuration: which tax codes map to which products, which nexus locations are active and how exemption certificates are handled. This owner signs off on changes before they reach production. Without a named owner, configuration drift tends to appear after the first tax rule change.
Address validation and data quality
Confirm whether your customers' addresses will be checked before tax is calculated, and who owns the rules for rejected or ambiguous addresses. Calculation quality depends on clean ship-to data, so ask your checkout and data teams what address fields are required and how they are stored. Document this decision before testing, because it changes both the checkout experience and the tax results.
Configuration sequence for Commerce AvaTax
This sequence takes a Drupal Commerce store from a clean module install to a verified tax calculation against AvaTax sandbox, so each setting is confirmed before live orders depend on it. Each step closes with a check the team can repeat after any later change.
Install the module and its dependencies with Composer
A developer adds the Commerce AvaTax module and the Drupal Commerce modules it depends on through Composer, so versions are pinned in the project's composer.json and composer.lock rather than copied by hand. Confirm the exact module name, its supported Drupal Commerce versions and its Drupal core compatibility on its Drupal.org project page before choosing versions. The step is done when the modules appear in the module list, the site's status report is clean, and the lock file is committed to version control.
Store AvaTax credentials outside the database
The team places the AvaTax account ID, license key and any service URL in environment-level secrets, such as server environment variables or the secret store your hosting platform provides, and references them from settings.php or the module configuration rather than typing them into the Drupal admin form. Confirm with your AvaTax account administrator which credentials apply to sandbox and which to production, and keep them separate. The step is done when the database contains no plain-text license key, which a developer can verify by searching the configuration export for the key value.
Set the company code and sandbox or production mode
An administrator enters the company code issued in the AvaTax account and selects sandbox mode for the first configuration pass. The company code must match the entity that files returns, so confirm it with the finance or tax owner before saving. The step is done when the module reports a successful connection to the sandbox endpoint from the status or test connection function, and the mode indicator in the configuration page shows sandbox.
Map product types to AvaTax tax codes
A store administrator and a tax owner assign an AvaTax tax code to each Commerce product type or product variation that needs one, using the tax codes that match what the business sells, such as physical goods, digital products or services. Taxability varies by state and locality, so the tax owner should confirm each mapping against the AvaTax tax code documentation and their own tax advice. The step is done when every active product type has a mapped code and a test product of each type shows a code in its line item data.
Configure origin address and default tax settings
The administrator enters the store's origin address, which AvaTax uses to source the sale, and sets default tax behavior in the store, including how tax is displayed at checkout and whether prices are entered with or without tax. Confirm the sourcing rules that apply to your shipments with the tax owner, since they determine which jurisdiction is charged. The step is done when a test cart with a known shipping address shows a tax amount in the order summary that matches the origin and destination you expected.
Enable address validation if the module supports it
If the installed AvaTax module version provides address validation, the team enables it in the module settings and tests it against addresses known to be valid and invalid in the sandbox, confirming how the checkout form responds to each. Do not assume the feature exists; check the module's documentation for the version you installed. Decide with the business whether validation blocks checkout, warns the shopper or only logs the result. The step is done when the test addresses produce the expected outcome and the chosen behavior is written into the configuration notes.
Run sandbox test orders and confirm tax lines
A tester places orders covering each mapped product type, a shipping charge, a discount, a multi-item cart and at least one exempt or edge case, all against the sandbox. Open each completed order record and confirm the tax lines show the AvaTax transaction reference, the expected jurisdictions and the expected amounts, then compare a sample against the figures the tax owner calculated independently. The step is done when every test order matches expectations, and the results are saved as the baseline for the production switch-over and for regression tests after updates.
Mapping store data to AvaTax tax fields
This table traces each piece of order data the connector sends to AvaTax, from the Drupal Commerce source to the AvaTax concept it feeds and the person who should decide its value. Confirm exact field names in the module's code and the AvaTax API documentation, not from memory, before you write any mapping.
| Data item | Drupal Commerce source | AvaTax concept | Who decides the value |
|---|---|---|---|
| Store origin address | Store entity address, checked against the store used for the order | Ship-from address on the tax request | Finance or tax lead, with the store owner |
| Customer shipping address | Shipping profile on the order, after address validation | Ship-to address on the tax request | Store owner, based on where goods are delivered |
| Line items and quantities | Order items and their quantities at the time of tax calculation | Line entries with quantity and amount | Developer and store owner, confirmed by testing |
| Unit prices and discounts | Order item unit price and promotion adjustments | Line amounts after discounts | Finance, which sets pricing and discount rules |
| Shipping charges | Shipping adjustments on the order | Separate freight or shipping line | Tax lead, based on whether shipping is taxable in each state |
| Product tax codes | Tax code field on each product or variation | Tax code on each line | Tax lead, with product or category owners |
| Customer exemption certificates | Customer account or profile field linked to the order | Customer code and exemption status | Tax lead, after certificate review |
| Currency | Order currency code | Currency code on the request and response | Finance, aligned with store currency settings |
Protecting credentials, customer data and tax settings
AvaTax calculations touch account credentials, customer addresses and tax configuration that determine what a customer is charged. The cards below cover the controls that keep those assets contained, and they map to the parts of the integration a security review will ask about first.
Keep AvaTax credentials out of exported config
Store the AvaTax account ID and license key in environment-level secrets or a secrets manager, not in the Drupal configuration that gets exported to Git. Configuration exports are routinely copied into tickets, staging databases and developer laptops, so a credential stored there should be treated as exposed. Ask your team to confirm which environment variables the module reads in your build and to verify that a configuration export contains no key material.
Restrict who can change company code
The company code and the production or sandbox mode setting decide whether live tax calculations and filings are generated from real transactions. Limit permission to change these settings to a named role, and log every change made through the administrative interface. A sandbox setting left active in production produces tax figures that do not match your filings, so review these values as part of every release.
Send only what the calculation needs
An AvaTax request needs the line items, quantities, amounts, ship-from and ship-to addresses and the customer's tax exemption status where relevant. It does not need names, email addresses, phone numbers or payment details. Review the payload the module builds for your order type, and remove any extra fields that a custom module or the checkout pane adds, so that third-party tax processing receives the smallest data set that produces a correct result.
Log API failures without addresses
When a tax request fails, the log entry should record the order reference, the error code, the HTTP status and the time, not the full ship-to address or any payment information. Logs are often shipped to a central platform with broader access than the store database. Confirm with your team how the module logs errors, what the logging channel captures in your environment, and who can read those entries.
Patch the module and Drupal core
Subscribe to Drupal Security Team advisories for Drupal core and for Commerce AvaTax, and plan updates against the Wednesday security release windows. Keep a record of which versions run in each environment so that an advisory can be matched to your site within a working day. Drupal 10 reaches end of life on December 9, 2026, so an AvaTax site that stays on it will fall outside security coverage on that date.
Test checkout after every update
Run a scripted checkout in staging after each core, Commerce or AvaTax update. Cover a taxable order, a non-taxable order, a multi-state ship-to address, an exempt customer and a failed API call, and compare the tax lines with values you have confirmed against the AvaTax sandbox. Record the results so that a change in tax behavior can be traced to a specific update.
Common Commerce AvaTax failures and fixes
This table lists the failures teams most often hit when running Commerce AvaTax on Drupal Commerce, with the likely cause, how to confirm it in logs or the order record, and the fix. Work through it when tax totals look wrong or checkout breaks, and confirm each cause against your own configuration and AvaTax account before changing production settings.
| Failure | Likely cause and how to confirm | Fix |
|---|---|---|
| Tax returns zero on taxable orders | Product tax codes are missing or wrong, or the store origin address is incorrect. Check the tax lines on the order record and the request payload in the AvaTax call log for empty or generic tax codes. | Assign correct product tax codes to each product type, verify the origin address in store settings, then re-run a test order and confirm tax lines appear. |
| Checkout errors when the AvaTax endpoint is unreachable | Outbound network egress is blocked from the web nodes, or the TLS trust chain for the AvaTax host is not trusted by the runtime. Look for connection timeouts or certificate errors in the Drupal watchdog or PHP error log. | Allow outbound HTTPS to the AvaTax host from the application tier, install the required CA bundle, and set a clear fallback behavior agreed with your tax owner. |
| Sandbox results used in production | The module is still in development mode, so requests go to the sandbox environment and return non-production tax figures. Check the mode setting in the AvaTax configuration and the account used in the credentials. | Switch the mode to production, replace sandbox credentials with production credentials stored in your secrets manager, then place a test order and compare results with your tax reference. |
| Rounding differences between line and order totals | Tax is computed per line and summed differently from the order-level total, or currency precision is set differently between Commerce and AvaTax. Compare the sum of line tax amounts with the order tax total on the order record. | Confirm the rounding mode and precision with your finance team, align the Commerce currency settings, and reconcile a sample of orders before go-live. |
| Shipping taxed incorrectly | Shipping is not mapped to the correct tax treatment in AvaTax, or the shipping adjustment is excluded when it should be included. Check the shipping line in the request payload and the tax lines attached to the shipping adjustment. | Set the shipping tax code to match the rules for each jurisdiction you sell into, then verify with sample orders for taxable and non-taxable shipping. |
| Address validation rejects valid addresses | The address validation service returns a mismatch for addresses that are valid but formatted differently, such as secondary unit designators or new ZIP codes. Look for validation error messages in the checkout log and the address payload sent for review. | Allow customers to confirm the entered address when the service suggests a change, avoid hard blocks at checkout, and review rejected addresses in a support queue. |
Which tax duties stay with your business
Calculating tax at checkout does not discharge your tax obligations. Commerce AvaTax can determine the rate for each order, but it does not file returns, remit the tax you collected, decide where you have nexus or verify exemption certificates. Those duties stay with the business that operates the store, and the store team must assign each one to a named owner before launch. Ask your tax advisor which states require registration for your sales, and record that answer in writing so the AvaTax configuration can be checked against it.
Four responsibilities need owners. First, registration in each state where you have nexus, including the sales tax permit and the filing frequency the state assigns. Second, return filing and remittance on the dates each state sets, which the store does not perform. Third, reconciliation: someone must regularly compare the tax recorded in AvaTax against the tax stored on Drupal Commerce orders, including the order totals, shipping charges and any tax-exempt customers, and investigate differences before a return is filed. Confirm with your advisor how often this should run and who signs off on the figures.
Refunds and cancellations need the same care as sales. When an order is refunded or cancelled, the tax associated with it must be reversed in AvaTax as well as in the store, or the period's reported tax will be wrong. Partial refunds, returned shipments and orders edited after payment are the usual sources of mismatch, so test each path on a staging site and document what the team does. DeployOpen does not give tax advice. Confirm the obligations that apply to your business with a qualified tax advisor, and ask your implementation partner to show exactly how each event reaches AvaTax.
Questions buyers ask before outsourcing Commerce AvaTax
What drives the cost of an AvaTax integration in Drupal Commerce?
The main drivers are how many stores, currencies and sales channels the site runs, how many product tax codes the catalog needs, how many origin addresses ship goods from, and how many special cases apply. Refunds, partial refunds, exemption certificates, marketplace or wholesale orders, and shipping and handling taxability each add configuration and test cases. Testing depth matters too: a store with a few US states and simple products needs a far smaller test matrix than one selling taxable and exempt goods across dozens of jurisdictions. Ask any partner for a written quote that lists each of these items separately, with the environments it will be tested in and what is excluded.
Which costs are one-time and which recur after launch?
The build work is one-time: module setup, tax code mapping, origin and nexus configuration, checkout and order-flow changes, and testing. Recurring costs fall into three groups. The AvaTax subscription and any per-transaction or address fees are paid to Avalara under its own terms, so confirm them directly with the vendor. Module maintenance covers applying Drupal Commerce and contributed module updates, since Drupal core releases follow a fixed schedule and security releases arrive on a set day each month. Tax-setting reviews are recurring because rates, product taxability rules and state requirements change, and someone must confirm the configuration still matches your obligations.
Can our internal team implement AvaTax tax calculation without a partner?
Often yes, if you have a Drupal developer who has built Commerce customizations and someone who can own the tax configuration. The module work is mostly configuration plus integration code, but the risky parts are data quality and edge cases: product tax codes, address validation at checkout, handling of refunds and voids, and how tax is recorded on orders. Teams usually struggle when no one owns the tax rules after go-live. Before deciding, list who will write the test cases, who will sign off on tax outcomes, and who will receive changes from Avalara and from the Drupal Security Team advisories that affect the stack.
How long does an AvaTax implementation take, in steps?
A realistic plan follows steps rather than a fixed number: confirm the tax obligations and registrations with your tax advisor, collect product tax codes and origin addresses, set up the Avalara account and sandbox credentials, install and configure Commerce AvaTax, connect address validation, map tax to checkout and order totals, build refund and void handling, run test orders against the sandbox, and then verify the production configuration before go-live. Each step can wait on a decision from finance or tax staff, so the calendar depends mostly on how quickly those decisions are made. A written plan from a partner should show each step, its dependency and the approver, rather than a single duration.
What do finance and tax teams need to provide for this work?
The tax team must decide which jurisdictions you are registered in or must collect in, which product categories are taxable where you sell, and which customers are exempt and what evidence they must provide. Finance needs to confirm how tax appears on invoices, how it posts to the general ledger, and who approves changes to rates or rules. Engineers will also need a list of refund scenarios, sample order exports, and access to the sandbox and production accounts. Ask any partner to name these inputs in the quote, because missing decisions are the most common reason an implementation stalls.
Does DeployOpen provide tax advice for our sales tax obligations?
No. DeployOpen implements, configures and tests the Commerce AvaTax integration in your Drupal site, and it can document how the calculation is set up so your tax advisor can review it. It does not decide which jurisdictions you must register in, which products are taxable, or how exemptions should be applied, and it does not issue tax opinions. Those decisions belong to your tax advisor, your finance team and, where relevant, Avalara's own guidance. Put this division of responsibility in the written scope so each party knows what it owns.
What does tax reporting remain our responsibility after launch?
Your organization remains responsible for filing returns, remitting collected tax, retaining records and responding to audits. The integration can help by making sure the tax amount on each order is calculated consistently and recorded in a form your finance system can export, but filing is handled through your own processes or your tax service provider. Ask for the exact order fields and exports the integration produces, and confirm with your advisor how long records must be kept in your jurisdictions.
How DeployOpen works on this
DeployOpen plans, implements, customizes, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For Drupal Commerce sales tax with AvaTax, we start from a written scope that names the tax rules, address checks and reporting handoffs your team needs, then build and test the integration in your environment.
How we scope
- We confirm which states, product categories and order types your AvaTax setup must cover before any build work starts.
- The written scope lists which Commerce AvaTax settings, address validation steps and reporting outputs are included and which remain with your tax team.
- Engagements are fixed-scope, so deliverables and timelines are agreed in writing before work begins, and a quote follows from that scope.
How we build
- We configure the AvaTax connection, tax types and product tax codes in a staging copy of your Drupal Commerce store first.
- We test checkout, refunds, order edits and exempt customers against sample orders that match your real tax scenarios, using your AvaTax sandbox where available.
- Custom code stays in version-controlled modules so later Drupal and Commerce updates can be reviewed and tested before they reach production.
How we hand over
- You receive a configuration record covering credentials handling, tax code mappings, address validation rules and the failure paths that are in scope.
- We document how tax calculations appear on orders, invoices and refunds so finance and support staff know where to look when a figure is questioned.
- Your team receives a written list of tax reporting duties that stay with you, such as filing, rate review and exemption certificate management.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, so tax integrations can be kept current with Drupal Commerce releases.
- Retainer work can include rechecking tax configuration after rate or product changes, and reviewing AvaTax module updates before they are applied.
- Confirm with your tax advisor and AvaTax account terms which support responsibilities sit with the vendor, the module maintainers and DeployOpen.
