Tax Rules

1. What a Tax Rule Is

Tax Rule (HaloPSA) – an automation that, at the instant an invoice is saved or regenerated, evaluates defined conditions (Top Level, Item Group, etc.) and writes the correct tax onto each invoice line.
Essentials
• Runs only on Save / Regenerate.
• More-specific rules outrank broader ones.
• Tax is written permanently; amounts will not change unless the invoice is regenerated.

---

2. Core Building Blocks

Element	Purpose at DTC	Example
Top Level	Combines Industry + Region/State to drive automations	Dental MD (dental offices in Maryland)
Item Group	Restricts tax to certain product families	Recurring Items (technology-service contracts)
Tax Rule	Stores rate + conditions; executes on save/regenerate	3 % tax for Dental MD technology services

---

3. Production Tax Rules (Current)

1. Virginia – 0 % on technology services → Top Level Dental VA
2. Maryland – 3 % on technology services → Top Level Dental MD
3. Guardian Dentistry Partners – VA sites → Site-specific override
4. Guardian Dentistry Partners – MD sites → Site-specific override

Validation tip: Create and save a sample invoice; inspect line-item tax amounts and totals.

---

4. Feature Gaps & Work-arounds

Need	Current Work-around	Status
Region-code filtering in Tax Rules	Separate site-specific rules for multi-state clients	Not yet supported (feature request logged)
Additional Top Levels for non-dental industries	Temporarily map to state-based dental Top Levels so tax applies	Technology and Government Top Levels created

---

5. Lifecycle & Recalculation Rules

Scenario	Required action	Reason
Recurring invoice line items	Enable Recalculate Tax on each line	Without it, lines keep original tax after rule changes
Templates & recurring profiles	After any rule change, open the profile → activate Recalculate Tax → save	Flag lives on the template; not retro-applied
Invoices already generated	Use Regenerate (or recreate) so new rules apply	Taxes are applied only at generation
Draft one-off invoices	Save again to trigger rule evaluation	Save recalculates tax

---

6. Known UI / Logic Quirks

• The Client/Site “Tax Rule” status column may lag behind actual rule execution; always verify by viewing the saved invoice lines.

---

7. Operational Checklist

1. Onboarding
   • Assign the most specific Top Level.
   • Place taxable products in the correct Item Group.
2. Testing
   • Generate & save a sample invoice; verify tax lines.
   • For recurring profiles, toggle Recalculate Tax and test.
3. When Tax Rules change
   • Update Templates/Recurring Invoices: ensure Recalculate Tax is enabled.
   • Regenerate outstanding invoices that must reflect new rules.
4. Rule maintenance
   • Keep the rule list lean—one rule per distinct scenario.
   • Document site-level overrides until Region-code support arrives.
5. Permissions
   • Only staff with Tax Rule rights should create or edit rules.