Shopify Order Held: Tax Lines Not Matched to a Tax Jurisdiction (US Sales Tax)
The Sales Document for Shopify order %1 cannot be created because Shopify Tax Matching could not resolve one or more tax lines to a Tax Jurisdiction. Open the order, choose Review Tax Match, assign a Tax Jurisdiction to every tax line, and approve the match on the review page.What It Means
US only. A Shopify order came in with tax lines such as 'NEW YORK STATE TAX at 4%'. Business Central needs a Tax Jurisdiction for each tax line and a Tax Area on the order. At least one tax line has no Tax Jurisdiction, so the connector holds the order and does not create the sales order or invoice. %1 in the message is the Shopify order number. A second variant reads: 'The Sales Document for Shopify order %1 cannot be created because a matched Shopify rate differs from the Tax Detail Rate.' That one means the jurisdiction was found, but the rate Shopify charged is not the rate in your BC Tax Details.
Root Cause
Shopify sends free-text tax line titles and rates, not BC codes. Business Central recalculates sales tax from its own setup when it creates the sales document, so each tax line must map to a Tax Jurisdiction, and the jurisdictions must form a Tax Area with Tax Details for the item's Tax Group. In the US version, the Shopify Connector NA extension's Shopify Tax Matching (a production-ready preview) suggests jurisdictions with AI. Learn states that an unidentified tax jurisdiction, or a difference between Shopify Rate % and Tax Detail Rate %, always holds the order for review, whatever the Tax Match Review Mode. Typical causes: no Tax Jurisdiction exists for that state/county/city, Auto Create Tax Jurisdictions is off, or the Tax Detail rate is out of date. Without Tax Matching, the Tax Area Code comes from the customer, or from the Tax Area Priority setting with the Customer Setup by Country/Region page.
Step-by-Step Fix
- Search for 'Shopify Orders' and open the held order. Read the error text: 'could not resolve one or more tax lines' means a missing jurisdiction; 'rate differs from the Tax Detail Rate' means a rate conflict.
- Open the 'Tax Lines' page from the Shopify Order page. Note the title and rate of each line that has no Tax Jurisdiction Code.
- Choose 'Review Tax Match' (or 'Review and Approve Tax Match'). On the 'Tax Match Review' page, assign a Tax Jurisdiction Code to every tax line. If the right jurisdiction does not exist, create it from the related tax setup, with Tax Details for your Tax Groups.
- If Shopify Rate % differs from Tax Detail Rate %, find out which is correct. Approving keeps the Tax Detail Rate % for posting. 'Use Shopify Rate' updates a shared Tax Detail from the Shopify order date, which also affects other documents with that jurisdiction and tax group, so check the effective date first.
- Choose 'Approve'. This needs a jurisdiction on every tax line and rebuilds the Tax Area from the final assignments.
- Create the sales document from the Shopify Order page.
- To reduce repeats: on the Shopify Shop Card, review 'Auto Create Tax Jurisdictions' (off by default), 'Auto Create Tax Areas', and 'Tax Match Review Mode'. Keep tax jurisdiction codes and descriptions clear so the matcher can find them. If you do not use Tax Matching, set 'Tax Area Priority' and fill Tax Area Code on the Customer Setup by Country/Region page or on the customer/template.
Verification Steps
Sources & References
- https://github.com/microsoft/BCApps/blob/main/src/Apps/NA/ShopifyNA/app/src/Tax%20Matching%20Agent/Codeunits/ShpfyTMAEvents.Codeunit.al
- https://github.com/microsoft/BCApps/pull/7453
- https://github.com/microsoft/BCApps/pull/12561
- https://github.com/microsoft/BCApps/pull/13209
- https://learn.microsoft.com/en-us/dynamics365/business-central/shopify/shopify-tax-matching
- https://learn.microsoft.com/en-us/dynamics365/business-central/shopify/synchronize-orders
Early Access · 30-Day Sandbox Pilot
Stop Order Sync Failures Before Customers Notice
The Order Flow Doctor monitors Microsoft Dynamics 365 Business Central order flows across Shopify, EDI (TrueCommerce, SPS), 3PLs, and carriers. Get automated root-cause diagnosis and one-click fixes.