Tax Rules

1. What a Tax Rule Is

Tax Rule (HaloPSA):
An automation that, at the instant an invoice is saved or regenerated, evaluates a set of conditions (Top Level, Item Group, etc.) and writes the correct tax onto each invoice line.
Key properties
• Runs only on Save / Regenerate—ideal for testing with sample invoices.
• Applies in order of specificity (narrowest conditions win).
• Writes a permanent record; tax is not an overlay and will not change unless the invoice is regenerated.

---

2. Core Building Blocks

Term	Purpose in DTC’s configuration	Example
Top Level	Combined Industry + Region/State label driving automations, including tax.	Dental MD (dental offices in Maryland)
Item Group	Restricts tax to certain product families.	Recurring Items (technology-service contracts)
Tax Rule	Container for rate + conditions; fires at invoice save/regenerate.	3 % tax for Dental MD on 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: Ignore the Client/Site “Tax Rule” column—create and save a test invoice to confirm the correct tax.

---

4. Feature Gaps & Work-arounds

Need	Current Work-around	Status
Region-code filtering of Tax Rules	Create separate site-specific rules for clients operating in multiple states	Not yet supported (feature request logged)
Additional Top Levels for non-dental industries (Technology, Government, etc.)	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	Set Recalculate Tax = On for each line.	Without it, the line retains its original tax after rule changes.
Templates & recurring profiles	After any rule change, open the profile ➔ enable/confirm Recalculate Tax , then save.	The flag lives on the template; it is not retro-applied.
Invoices already generated	Use Regenerate (or recreate) so new rules apply.	Taxes only apply at generation; existing invoices do not update automatically.
Draft one-off invoices	Simply save again to trigger rule evaluation.	Save action recalculates tax.

---

6. Known UI / Logic Quirks

• “Tax Rule” toggles can be out-of-date; rely on invoice lines after save/regenerate.
• Test-invoice feedback sometimes appears inconsistent; stored invoice data is authoritative.

---

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 is released.
5. Permissions
   • Only staff with Tax Rule rights should create or edit rules.