[Shopify] Copilot Tax Matching + Tax Area/Tax Liable/Tax Exempt support

[onbuyuka]

Summary

Adds LLM-powered tax jurisdiction matching for Shopify orders, foundational tax field support across orders and refunds, and a human-in-the-loop (HITL) review layer — a configurable blocking approval gate (default on) plus audit trail, persistent badge, active notification, and a rate-conflict guard — so every Copilot decision is traceable, visibly marked, and gated for review without silently breaking auto-create-sales-doc or background sync flows. Product-line and shipping-charge tax lines are matched as first-class citizens.

What this PR does

When a Shopify order is imported, it carries free-text tax line descriptions (e.g. "NEW YORK STATE TAX at 4%") on both product lines and shipping charges. Business Central needs structured Tax Jurisdiction codes and a Tax Area to apply correct tax rules. Today this mapping is manual. This PR automates it using Azure OpenAI, adds the underlying tax infrastructure to the connector, and wraps the AI decisions in a human-in-the-loop review layer — holding back Sales Document creation until a user approves by default, and always holding when Business Central's own tax rate would differ from what the customer paid on Shopify — aligned with RAI feedback that automated tax matching should never run silently.

Areas of change

1. Standard connector — Tax fields and mapping (6 files)

File	Change
ShpfyOrderHeader.Table.al	New fields: Tax Area Code (1070), Tax Liable (1080), Tax Exempt (1090)
GetOrderHeader.graphql	Add taxExempt to GraphQL query
ShpfyImportOrder.Codeunit.al	Parse taxExempt from Shopify JSON
ShpfyOrderMapping.Codeunit.al	New MapTaxArea procedure (called in B2C + B2B paths), OnAfterMapShopifyOrder event + fire
ShpfyProcessOrder.Codeunit.al	Read Tax Area Code + Tax Liable from order header (instead of calling FindTaxArea at doc creation time)
ShpfyOrder.Page.al	Display Tax Area Code, Tax Liable, Tax Exempt

Tax Area mapping now happens during order mapping (upstream) rather than during sales document creation (downstream). This means Copilot and other extensions can modify the Tax Area via the OnAfterMapShopifyOrder event before the sales document is created.

MapTaxArea respects Tax Exempt: if the Shopify order has taxExempt = true (e.g. POS cashier disabled tax), the Tax Area Code is still set for reporting but Tax Liable stays false.

2. Standard connector — Refund tax propagation (3 files)

File	Change
ShpfyRefundHeader.Table.al	FlowFields 110-112: Tax Area Code, Tax Liable, Tax Exempt (from parent order)
ShpfyCreateSalesDocRefund.Codeunit.al	Set Tax Liable alongside Tax Area Code on credit memos (bug fix — was only setting Tax Area Code)
ShpfyRefund.Page.al	Tax group (3 fields) + Tax Lines navigation action (reuses existing Order Tax Lines page)

3. Standard connector — Integration points for Copilot (1 file)

File	Change
ShpfyOrderEvents.Codeunit.al	New OnAfterMapShopifyOrder integration event

The Copilot subscriber also reuses the existing OnAfterCreateSalesHeader event to propagate the HITL marker. The Tax Jurisdiction Code field on Shpfy Order Tax Line is not in the connector — it lives in the Copilot app's TableExt since the connector itself never reads or writes it.

4. Copilot Tax Matching app (CopilotTaxMatching/app/)

Separate app (ID range 30470-30499) that subscribes to OnAfterMapShopifyOrder, OnBeforeCreateSalesHeader, and OnAfterCreateSalesHeader. Architecture:

OnAfterMapShopifyOrder event
  -> Events (30473): guards (enabled? capability active? not exempt? no tax area yet?)
  -> Matcher (30471): gather tax lines (product-line AND shipping-charge) + jurisdictions
                      + address -> call GPT-4.1 -> parse matches
  -> ApplyMatches: write jurisdiction codes to tax lines, create jurisdictions if allowed,
                   seed a Tax Detail bracket per line from its own rate + tax group, and
                   flag a rate conflict when BC's existing rate differs from Shopify's
  -> FixReportToJurisdictions: point every matched jurisdiction with a blank Report-to at
                   the state-level jurisdiction (admin-maintained hierarchies left untouched)
  -> Builder (30472): find or create Tax Area from matched jurisdictions -> set on order header
  -> Activity Log (30477): per-line + per-area Activity Log entries (Type=AI)
  -> Set "Copilot Tax Match Applied" + "Copilot Tax Rate Conflict" on order header

OnBeforeCreateSalesHeader event  [blocking gate]
  -> Events (30473): if Copilot-matched + not yet approved + (shop requires review
                     OR order has a rate conflict) -> Handled := true (skip Sales Doc
                     creation; order waits until the user approves on the review page)

OnAfterCreateSalesHeader event
  -> Events (30473): propagate Copilot Tax Match Applied marker to Sales Header (badge only)

Review surfaces (all open the Copilot Tax Match Review page, 30471)
  -> Shpfy Order page (30479): Review and Approve / Review Copilot Tax Match action
                               + actionable "Review" notification fired on open
  -> Sales Order page (30476): Review Copilot Tax Match action + one notification
                               (non-blocking mode), derived live from the order's
                               Reviewed flag + My Notifications (no table)

Key design decisions:

• Forced function calling — LLM must return structured JSON via match_tax_jurisdictions tool, not free text
• Temperature 0 — deterministic results for identical inputs
• Confidence levels — high/medium matches applied directly; low (new jurisdictions) only with admin opt-in
• First-class shipping — shipping-charge tax lines (stored on Shpfy Order Tax Line keyed by Shopify Shipping Line Id) are matched and seeded exactly like product-line tax lines; each line seeds its own Tax Detail bracket from its own rate and tax group (a shipping line uses the Shop's Shipping Charges Account tax group)
• No PII sent — only tax line titles, jurisdiction codes/descriptions, and city/state/country

Objects: 9 codeunits (Register, Matcher, Builder, Events, TaxMatchFunction, Install, Upgrade, Notify, Activity Log), 4 table extensions (Shop, Order Header, Sales Header, Order Tax Line), 4 page extensions (Shop Card, Sales Order, Order, Order Tax Lines), 1 Card page (Copilot Tax Match Review), 1 ListPart page (Tax Lines, embedded on the review page), 1 enum extension, 1 permission set. Config UI is 5 fields on the Shop Card page (dependent fields disabled until their prerequisite is set). The notifications are stateless — no dedicated table. New Shop config fields are backfilled onto pre-existing shops on install/upgrade via a shared, upgrade-tag-guarded routine (see Shop config defaults below).

5. Human-in-the-loop (configurable blocking, default on)

Five pillars deliver review of every Copilot decision, centered on a dedicated Copilot Tax Match Review page (a per-order Card summarizing the resolved Tax Area and each tax line's matched Tax Jurisdiction Code, with the platform AI confidence indicators):

• Configurable blocking review (default on) — a per-shop Copilot Tax Match Review Required Boolean (default true) and a per-order Copilot Tax Match Reviewed Boolean gate Sales Document creation. ShpfyCopilotTaxEvents subscribes to OnBeforeCreateSalesHeader and sets Handled := true when the order was Copilot-matched, has not yet been approved, and (the shop requires review OR the order has a Copilot Tax Rate Conflict) — so the connector (auto-create, manual action, and background job) skips Sales Doc creation and the order stays a Shopify order pending review. The Shpfy Order page exposes a Review and Approve Copilot Tax Match action (captioned just Review Copilot Tax Match once approved or when not held) that opens the review page; clicking Approve there rebuilds the Tax Area from the current line jurisdictions, re-detects rate conflicts, flips Copilot Tax Match Reviewed, and the next process run creates the document. Clearing the shop toggle opts into non-blocking mode (but a rate conflict still holds).
• Rate-conflict guard — the Copilot Tax Rate Conflict Boolean (order header field 30478) is the single source of truth for a rate conflict: it is set at match time when a matched line's existing BC Tax Detail rate (for that line's tax group, valid as of the order date) differs from Shopify's, and refreshed whenever the match is re-applied on Approve. The gate, the notifications, the order-page action caption, and the review-page guidance + Approve visibility all read this one flag, so they can never disagree. A rate conflict holds the order in both blocking and non-blocking mode — Business Central's own rate is never auto-posted in place of what the customer paid on Shopify without a human accepting it. This applies uniformly to product-line and shipping-charge tax lines.
• Review page — the single canonical review-and-adjust surface. Shows the resolved Tax Area (with AI confidence indicator), the ship-to context, and the tax lines ListPart. Each line shows the item (or shipping charge) it taxes, Shopify's rate, the Business Central Tax Detail rate that would apply as of the order date, and the matched Tax Jurisdiction Code (with confidence indicators). The Tax Jurisdiction Code is editable so a reviewer can correct or complete a match, and the row is highlighted green when the two rates agree and red when they differ. Approve (shown only while the order is held and not yet reviewed) rebuilds the Tax Area, re-seeds missing Tax Detail brackets, re-detects conflicts, and is blocked while any line is still unmatched; it errors (without releasing the order) if no Tax Area can be resolved. An Undo Approval action reverses an approval while the order is still held and no Sales Document exists yet. Jurisdiction edits take effect only on Approve and are reverted if the page is closed without approving; OnQueryClosePage warns on a pending approval. On a rate conflict the reviewer has a third option beyond accepting BC's rate or changing the jurisdiction: a Use Shopify Rate action on the tax lines part creates/updates a Tax Detail (effective the order's document date, at Shopify's rate) so BC posts what the customer paid. It confirms first that this changes shared BC tax setup (not just this order), is enabled only on a real rate difference, and updates a same-date bracket in place; after it runs the row turns green and Approve then clears the conflict. (The tax lines ListPart was moved here off the Shopify Order Card.)
• Audit trail — every matched tax line and the resulting Tax Area each get a System Application Activity Log entry of Type AI (via Activity Log Builder), carrying the LLM's confidence, reasoning, and a drill-back URL. On a rate conflict, the per-line entry explains the difference. The platform renders these as small AI confidence indicators next to the corresponding fields on the review page.
• Persistent badge + active notifications — a Copilot Tax Match Applied Boolean propagates from the Shpfy Order Header onto the BC Sales Header (read-only field + Review Copilot Tax Match action on the Sales Order page). Actionable, dismissible BC Notifications prompt review: on the Shopify Order page (both modes, once per order/session) and on the Sales Order page (non-blocking mode). Each opens the review page and can be suppressed per-user (MyNotifications.Disable) via its own GUID. The Sales Order prompt is derived live from the originating order's Copilot Tax Match Reviewed flag + My Notifications (no per-user table).

Default is blocking. The conservative default puts a human gate before any Copilot-matched Sales Document is created — honoring RAI feedback. High-throughput merchants can opt into non-blocking automation explicitly per shop, where the review page + audit trail + badge + notification keep the AI's decisions from ever being silent — and a rate conflict still forces review regardless of the toggle.

The Shop Card fields have dependencies: Auto Create Jurisdictions/Areas and Review Required are disabled until Copilot Tax Matching Enabled is on, and the Tax Area Naming Pattern is disabled until Auto Create Tax Areas is on.

6. Tax Detail seeding + rate-conflict behavior

On every successful match, each tax line seeds its own Tax Detail for (jurisdiction × the line's tax group) — a product-line tax line uses the order line item's Tax Group Code; a shipping-charge tax line uses the Shop's Shipping Charges Account Tax Group Code. For each, it looks for the latest Tax Detail with Effective Date <= order date for that jurisdiction + tax group + tax type:

• No valid bracket exists → insert one at the order date with Shopify's rate (pure seeding).
• Bracket exists, rate matches Shopify → exit silently. Already correct.
• Bracket exists, rate differs from Shopify → leave the existing (admin-maintained) rate untouched, emit telemetry 0000UMR, and flag the order with a rate conflict (Copilot Tax Rate Conflict). The jurisdiction is still matched and the Tax Area is still built, but the order is held for human review so a person accepts BC's rate or corrects the detail — auto-inserting on divergence would silently propagate Shopify's rate to every posting after that date, which is admin territory.

Report-to rollup: when more than one jurisdiction is matched, FixReportToJurisdictions sets Report-to to the state-level (first) jurisdiction on every matched jurisdiction whose Report-to is still blank — including pre-existing jurisdictions and the state itself (which reports to itself). A jurisdiction that already has a Report-to (an admin-maintained hierarchy) is left untouched.

Shop config defaults (install/upgrade)

The Shop config fields carry their defaults as field InitValues (Auto Create Tax Areas = true, Tax Area Naming Pattern = 'SHPFY-', Copilot Tax Match Review Required = true), which only apply to shops created after the app is installed. Because Shopify shops usually already exist when this app is added, Shpfy Copilot Tax Upgrade (30478) backfills those three fields onto existing shops from an Init()'d record. The backfill is guarded by an upgrade tag so it runs exactly once per company, and is invoked from both the install trigger (OnInstallAppPerCompany) and the upgrade trigger (OnUpgradePerCompany); the tag is intentionally not registered in OnGetPerCompanyUpgradeTags, so a fresh install still backfills pre-existing shops (mirroring how Shpfy Installer guards its Cue/retention setup). The two opt-in booleans (Copilot Tax Matching Enabled, Auto Create Tax Jurisdictions) intentionally default to false and are left untouched. (Auto Create Tax Areas previously had no InitValue despite being documented as defaulting to true — now fixed.)

7. Copilot test app (CopilotTaxMatching/test/)

Two layers. AI Test Toolkit data-driven tests (YAML scenarios iterated by the framework, real LLM calls, no mocking):

• J1-J8: Jurisdiction matching (exact, partial, auto-create, medium confidence, duplicates)
• H1-H12: Hard/adversarial matching (similar codes across states, truncated titles, 15+ distractors, Canadian HST/GST/PST, French tax abbreviations, geographic disambiguation)
• JC1-JC6: Jurisdiction creation details (country/region, report-to hierarchy incl. pre-existing blank Report-to, description = code)
• TD1-TD8: Tax detail creation including effective date and rate-divergence preservation
• RD1-RD9: Rate divergence / conflict (item + multi-line conflicts, held in blocking and non-blocking mode, resolve-then-approve, edit discarded on close, Undo Approval)
• S1-S7: Shipping-charge tax lines (bracket seeded at the shipping line's own rate, new-jurisdiction, untaxed shipping, empty/shared tax group, multiple charges, shipping rate conflict holds the order)
• TA1-TA11: Tax area find/create (exact match, superset/subset, collision, naming patterns)
• G1-G8: Guard / early-exit scenarios (Copilot disabled, tax area pre-set, tax exempt, no order lines, result=false)
• F1-F6: End-to-end flows

Plain unit tests (standard test runner, no LLM, no toolkit):

• Shpfy CT HITL Test (134716) — marker propagation, MarkReviewed, DisableForUser, Activity Log helpers, Capitalize confidence mapping
• Shpfy CT Rate Conflict Test (134720) — rate-conflict recheck/flip on approve, the creation gate (IsSalesDocumentCreationHeld) in blocking and non-blocking mode, the business guards (ShouldAttemptMatch), Undo Approval, shipping bracket seeding + shipping rate conflict, and the Report-to rollup on re-apply (blank Report-to set, admin-set Report-to preserved)

8. Standard connector tests (3 tests)

Test	Codeunit	What it verifies
UnitTestCreateSalesDocumentTaxLiable	139608	Tax Liable flows from Shpfy Tax Area → MapTaxArea → sales document
UnitTestCreateSalesDocumentTaxExempt	139608	Tax Exempt order gets Tax Area Code but Tax Liable stays false
UnitTestCrMemoInheritsTaxAreaAndTaxLiable	139611	Credit memo inherits Tax Area Code + Tax Liable from parent order

9. Documentation (in CopilotTaxMatching/app/)

• Architecture.md — execution flow (incl. HITL writes, rate-conflict handling, shipping tax lines, Report-to rollup, Tax Detail seeding), object inventory, LLM config, data model, integration points, telemetry
• TestMatrix.md — full test scenario inventory + the Automated Test Coverage map

How to review

1. Start with Architecture.md for the big picture — the HITL + rate-conflict sections are the primary RAI surface
2. Connector changes: ShpfyOrderMapping.Codeunit.al (MapTaxArea + event), ShpfyProcessOrder.Codeunit.al (simplified tax handling), ShpfyCreateSalesDocRefund.Codeunit.al (bug fix)
3. Copilot core: ShpfyCopilotTaxMatcher.Codeunit.al (LLM logic, per-line Tax Detail seeding, rate-conflict detection, Report-to rollup, shipping-charge handling), ShpfyCopilotTaxEvents.Codeunit.al (guards, gate, propagation), ShpfyTaxAreaBuilder.Codeunit.al
4. HITL layer: ShpfyCopilotTaxReview.Page.al (Approve/Undo, editable jurisdiction, green/red rates), ShpfyCopilotTaxNotify.Codeunit.al, ShpfyCTActivityLog.Codeunit.al, page extensions on Sales Order and Shpfy Order pages
5. Tests: ShpfyCTMMatchTest.Codeunit.al (LLM-driven), ShpfyCTHITLTest.Codeunit.al + ShpfyCTRateConflictTest.Codeunit.al (non-LLM behavior), CTM-TS-*.yaml (data-driven scenarios)

Test plan

• Compile Shopify connector app
• Compile Copilot Tax Matching app + test app
• Run connector unit tests (codeunit 139608, 139611)
• Run Copilot unit tests (codeunit 134716 HITL, 134720 rate conflict) — non-LLM behavioral coverage
• Run Copilot AI Test Suite (CTM-UNIT) — YAML-driven scenarios with real LLM calls, incl. shipping (S*) and rate divergence (RD*)
• Manual: import a Shopify order with product + shipping tax lines → verify Tax Area Code + Tax Liable set, per-line Tax Detail seeded from each line's own rate/tax group, Activity Log entries appear, marker set on Shpfy Order Header
• Manual: create Sales Document from the order → verify marker propagates, "Review Copilot Tax Match" action visible, one-time notification fires on first open
• Manual: rate-conflict order (existing Tax Detail at a different rate) → order is held in both blocking and non-blocking mode, the divergent line shows red on the review page, Approve rebuilds + releases, Undo Approval re-holds; telemetry 0000UMR emitted
• Manual: on a rate-conflict line, click Use Shopify Rate → confirm warning shown, Tax Detail created/updated at the document date with Shopify's rate, row turns green, Approve clears the conflict; telemetry 0000UNP emitted
• Manual: install/upgrade into a company that already has shops → existing shops get Auto Create Tax Areas, Tax Area Naming Pattern, and Copilot Tax Match Review Required defaults; the two opt-in booleans stay off
• Manual: tax-exempt POS order → Copilot skipped, no marker, no Activity Log entries
• Manual: process refund → credit memo gets Tax Area Code + Tax Liable from parent order

Fixes AB#445769

[github-actions]

AL Documentation Audit

Documentation gaps were detected in the following apps:

• Shopify-Connector-Test: 0% documentation coverage
• Shopify-Copilot-Tax-Matching-Tests: 0% documentation coverage
• Shopify-Copilot-Tax-Matching: 0% documentation coverage

To generate documentation, run /al-docs init or /al-docs update using GitHub Copilot CLI or Claude Code.
This review is for awareness to help keep documentation in sync with code changes. It is okay to dismiss this request.