Skip to content

Common problems

Symptoms first, in rough order of how often they come up.

Contacting support? Send a diagnostics file first

If the checks on this page do not solve it, create a diagnostics file and attach it to your ticket — from the order itself if the problem is about one order. It gives support your settings, versions, logs and a live connection test in one go, so they can start on the answer instead of asking questions. See Sending diagnostics to support.

No tax is charged at all

Is TaxCloud enabled? Stores → Configuration → Sales → Tax → TaxCloud Settings → Enabled. Check you are looking at the right store view — see Multi-store setups.

Is the origin address complete? Missing or malformed origin ZIP stops the lookup happening. It needs the full ZIP+4.

Are the credentials valid? Click Verify Credentials. Rejected credentials mean every lookup fails.

Is the destination in the US? Orders shipping elsewhere are left to Magento. For orders to Canada, see No tax on Canadian orders.

Is the product's tax class None? Those are never sent to TaxCloud. See Assigning TICs.

Is the customer exempt? Check whether a certificate was applied — see How an order becomes exempt.

Did the call fail? With fallback off, a failed lookup means no tax. The log will say.

Is another tax extension installed? Only one extension can calculate tax. If another one has taken over, TaxCloud still shows as enabled and its credentials still verify, but it is not calculating. See Another extension is calculating tax.

No tax on Canadian orders

Is Calculate Canadian Tax set to Yes for that store view? And is that store view on V3 REST? See Canadian tax.

Does your TaxCloud account have Canada? Click Check Canada Access. If it says Canada is not enabled, contact TaxCloud support to enable it.

Is the address complete? The customer must pick a province and enter a valid Canadian postal code, such as M5H 2N2.

No tax on the cart page

Expected until the shopper gives a destination. Once they fill in Estimate Shipping and Tax on the cart page with a country, state and ZIP, an estimated tax appears. If it still does not:

  • Is the destination somewhere you collect? A state you do not collect in shows no tax, exactly as it would at checkout.
  • Is the ZIP valid for the state? A ZIP that does not belong to the chosen state cannot be priced. The reason is recorded in the log.
  • Is it a Canadian address? Canadian estimates need Canadian tax turned on.

See Estimated tax on the cart page.

The cart estimate differs from the tax at checkout

Expected in some ZIPs. The cart estimate is based on the ZIP alone; checkout uses the full street address. Where a ZIP crosses a city or district boundary, the two can differ. The amount charged at checkout is the correct one. See Estimated tax on the cart page.

A download-only order was taxed in the wrong state

Check the billing address on the order. An order made only of downloads, licences, virtual products or virtual gift cards has no shipping address — Magento skips the shipping step for it — so it is taxed against the billing address. Add anything shippable to the same basket and the whole order, downloads included, is taxed against the shipping address instead. See Digital and downloadable products.

A customer whose billing address is a company head office or a PO box in a different state from where they live will be taxed at the head office. That is the address you hold for them, and it is the one the sale is sourced to.

The tax amount looks wrong

Check the TIC first. This is the usual answer. A product taxed as general goods when it is clothing or food will be confidently wrong. See How TICs work.

Check the origin ZIP+4. A five-digit ZIP can span several jurisdictions.

Check the shipping TIC. 11010 and 11000 are taxed differently in several states — see Shipping and handling.

Is it cached? A figure from before your change may still be being served. Flush the TaxCloud cache and try again.

Is fallback masking the problem? With fallback on, a failed lookup silently produces Magento's own rate instead of TaxCloud's. The number looks plausible and is not TaxCloud's. Check the log.

Percentages differ slightly from TaxCloud's dashboard

Normal — rounding. The amounts should match exactly. If the amounts differ, that is worth investigating.

Credentials are rejected

Re-copy them. A trailing space or a truncated paste is the usual cause.

Right API type? V1 credentials in the V3 fields will not work. The fields change with API Type.

Right connection? Integrations → Custom API in TaxCloud. A well-formed Connection ID that TaxCloud does not recognise means the wrong connection.

Right scope? Credentials saved at Default Config while you are testing a specific store view — or the reverse — is a common mix-up.

"Could not reach TaxCloud"

Not a credentials problem: your server cannot get out to TaxCloud. Ask your host about outbound HTTPS, a firewall, or a proxy. It affects everything the extension does.

Orders are missing from TaxCloud

Which capture trigger? With On payment or On shipment, orders that never reached that point were never reported. See Capture.

Calculations-only mode? Then nothing is ever reported, by design.

Did capture fail? Check the log around the order.

Which store? Orders from a store view with different credentials go to a different TaxCloud account.

Was it a download-only order? The log records which address each order was reported against. An order with no usable shipping or billing address cannot be reported at all, and the log says so by order number.

A refund is not showing in TaxCloud

Was there a credit memo? Refunding through your payment provider alone does not reach TaxCloud. Record it as a credit memo.

Was the order captured on a different API? An order created under V1 SOAP cannot be refunded under V3 REST, or vice versa. See Refunds.

Was the order ever captured? Nothing to reverse if it was not.

An exempt customer was charged tax

Work through the checklist in How an order becomes exempt. The most common causes are: they were not signed in, the certificate is listed but not attached, or the certificate does not cover the destination state.

A certificate change is not taking effect

Certificates are cached for an hour. Use Refresh from TaxCloud in the customer's certificate panel, or flush the TaxCloud cache.

Checkout has become slow

Is the TaxCloud cache type disabled? Then every page load calls TaxCloud. See Clearing the TaxCloud cache.

Is Cache Lifetime set to 0? Same effect, from the settings side.

Is TaxCloud responding slowly? Advanced logging records per-call timing. API Timeout caps how long a shopper waits.

The TaxCloud settings section is missing

The extension is not installed or not enabled. Check with bin/magento module:status Taxcloud_Magento2 — see Installing the extension.

The exemption certificates tab is missing

Either exemptions are off, or your admin role lacks the TaxCloud Exemption Certificates permission.

Still stuck

Gather this before contacting TaxCloud support:

  • The order number and roughly when it happened
  • What you expected and what you got
  • A log extract with Logging set to Enable - Advanced while reproducing it — see Reading the log
  • Your API Type, and whether the store is on a test or production connection