Tax Reporting & Compliance — User Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Purpose: This guide helps users understand how to work with tax forms, review them, and track distributions.

​

Table of Contents

• Overview
• Quick Reference
• Decision Tree
• Prerequisites
• Pre-Flight Checklist
• Getting Started
• Common Tasks
• Advanced Features
• Pattern Library
• Common Mistakes
• API Examples
• Tips and Best Practices
• Troubleshooting
• Related Documentation

​

Overview

​

Key Capabilities

• View tax years and their filing status
• Review generated tax forms (1099, W-2, quarterly reports)
• Approve forms for filing to IRS
• Track document distribution and delivery status
• Export forms for records and audit purposes

​

Who Should Use This Guide

​

Quick Reference

​

Decision Tree

1. Check filing status → Go to Tax Years → Click year → View status cards
2. Review a form before filing → Go to 1099 or W-2 Forms → Click form → Verify data → Click Approve
3. Resend a failed distribution → Go to Distributions → Filter by “Failed” → Verify email → Click Resend
4. Regenerate a form with updated data → Contact Admin (requires fa.tax.admin) → Admin regenerates from updated payroll/AP data
5. File a quarterly report → Go to Tax Reports → Select report → Verify data → Click “Mark as Filed”
6. Export a form for records → Open form detail page → Click “Download PDF”

​

Prerequisites

​

Permissions Required

Note: Contact your organization administrator if you don’t have the required permissions.

​

Pre-Flight Checklist

• You have the required permissions (fa.tax.view at minimum)
• You know the tax year you’re working with (e.g., 2025)
• You have access to vendor and employee master records
• You understand your organization’s tax filing timeline
• Payroll data is finalized for the relevant period (for W-2s)
• Vendor payment records are complete (for 1099s)
• Email addresses are verified for distribution recipients

​

Getting Started

​

Accessing Tax Reporting

1. Navigate to Finance & Revenue in the main menu
2. Click Tax Compliance
3. You’ll see the Tax Compliance Dashboard with all active tax years

​

Understanding the Dashboard

​

Common Tasks

​

Task 1: View a Tax Year

1. On the Dashboard, click Tax Years
2. Find the tax year you want (e.g., 2025)
3. Click on the year to open the Tax Year Detail page
4. You’ll see:
   • Year: Tax year (e.g., 2025)
   • Status: Active, In Review, or Closed
   • Progress: Number of forms generated, reviewed, ready to file
   • Forms Generated: Count of 1099s, W-2s, and reports

• Use the Filters to find years by status
• Closed tax years are read-only; historical forms remain accessible for audit

​

Task 2: Review 1099-NEC Forms (Vendors)

1. Navigate to 1099 Forms
2. Select the tax year
3. You’ll see a list of generated forms:
   • Vendor: Company name
   • EIN: Employer Identification Number
   • Gross Payments: Total amount paid during the year
   • Status: Pending Review, Ready to File
4. Click on a form to see details:
   • Vendor Address
   • Payment Breakdown (by month or category)
   • Form Type (1099-NEC default)
5. Verify the data:
   • Confirm vendor name and address are correct
   • Check that gross payments match your records
   • Review any notes or exceptions
6. Click Approved to mark the form Ready to File

• Use Filter by Status to focus on pending forms
• Compare gross payments with your Accounts Payable records
• If data is incorrect, contact your Administrator to regenerate the form

​

Task 3: Review W-2 Forms (Employees)

1. Navigate to W-2 Forms
2. Select the tax year
3. You’ll see a list of generated forms:
   • Employee: Name (SSN masked for security)
   • Wages, Tips, and Compensation: Year-to-date gross
   • Federal Tax Withheld: Total federal income tax
   • Status: Pending Review, Ready to Distribute
4. Click on a form to see details:
   • Employee Address
   • Year-to-Date Totals: Wages, other income, deductions
   • Tax Withholdings: Federal, state, Social Security
   • Box 12 Codes (401k, health insurance, etc.)
5. Verify the data:
   • Check gross wages against payroll records
   • Confirm tax withholdings are accurate
   • Review deductions and special codes
6. Click Approved to mark the form Ready to Distribute

• SSN is encrypted and only visible to tax admins (for security)
• Coordinate with Payroll if you see discrepancies
• Employee W-2s are typically distributed by January 31st

​

Task 4: Review and File Tax Reports (941 / 940)

1. Navigate to Tax Reports
2. Select the tax year
3. You’ll see quarterly (941) and annual (940) reports:
   • Report Type: 941 or 940
   • Filing Period: Q1, Q2, Q3, Q4, or Annual
   • Filing Status: Draft, Ready to File, Filed
   • Filed Date: When the form was submitted to IRS
4. Click on a report to see details:
   • Calculation Summary: Calculated tax liability
   • Quarterly Breakdown (for 941): Liability by quarter
   • Supporting Documentation: Links to payroll data
5. Verify the data:
   • Cross-check tax liability with your payroll system
   • Confirm filing period is correct
   • Ensure any adjustments are documented
6. Click Mark as Filed once IRS filing is confirmed

• 941 deadlines: Q1 (Apr 30), Q2 (Jul 31), Q3 (Oct 31), Q4 (Jan 31 next year)
• 940 deadline: January 31st (annual)
• Contact your tax accountant if liability seems unusual

​

Task 5: Track Tax Document Distribution

1. Navigate to Distributions
2. You’ll see all sent forms:
   • Form Type: 1099, W-2, etc.
   • Recipient: Vendor or employee name and email
   • Sent Date: When the form was emailed
   • Status: Sent, Read, Failed
3. Check Status:
   • Sent: Email delivered; waiting for recipient to open
   • Read: Recipient opened the email
   • Failed: Delivery error (e.g., invalid email address)
4. For Failed deliveries:
   • Verify the email address in Contacts or Payroll
   • Click Resend to retry delivery
   • If still failing, contact your Administrator

• Track Read status to confirm recipients received forms
• Resend failed distributions within 48 hours
• Use Filters to find forms by status or recipient type

​

Advanced Features

​

Exporting Forms for Records

1. Open a specific form detail page (1099, W-2, or tax report)
2. Click Download PDF (or Export)
3. The form downloads as a PDF for your records or archival

• Print for filing cabinet backup
• Email to external tax accountant or CPA
• Archive for audit purposes

​

Filtering and Searching

​

Pattern Library

​

UI Patterns and Expected States

​

Common Mistakes

​

API Examples

​

Fetching Tax Years (for Developers)

// Fetch all tax years for the current organization
import { supabase } from '@/integrations/supabase/client';

const { data: taxYears, error } = await supabase
  .from('fa_tax_years')
  .select('id, year, status, start_date, end_date, created_at')
  .eq('organization_id', organizationId)
  .order('year', { ascending: false });

if (error) {
  // Handle error — never expose raw error.message to users
  const message = sanitizeErrorMessage(error);
  // Use the platform's structured logger (never console.error in production)
  processLogger.error('Failed to fetch tax years', { error: message });
}

Note: Always include .eq('organization_id', organizationId) for multi-tenant isolation.

​

Tips and Best Practices

​

Do’s

​

Don’ts

​

Troubleshooting

​

Issue: Form Data Looks Incorrect

1. Check HR Payroll (for W-2) or Accounts Payable (for 1099) for the correct data
2. Contact your Administrator to regenerate the form with updated data
3. If still incorrect, escalate to your Finance Manager

​

Issue: Email Not Received by Recipient

• Email address is invalid or outdated
• Email ended up in spam folder
• Email server delivery failure

1. Verify the email address in Contacts or Payroll
2. Correct the address if needed
3. Click Resend on the Distribution page
4. Ask the recipient to check spam/junk folder
5. If still failing, contact your Administrator

​

Issue: Cannot Approve a Form

• You don’t have fa.tax.generate permission
• Form is already approved or filed
• System is still processing form data

1. Contact your Administrator to grant the fa.tax.generate permission
2. Check the form status; if already filed, no approval needed
3. Wait a few moments and refresh if the form is still loading

​

Related Documentation

• Admin Guide: docs/fa/tax-reporting-admin-guide.md - For managing tax years and settings
• Specification: specs/fa/specs/FA-10-tax-reporting-compliance.md - Technical details
• Integration Guide: docs/architecture/integrations/FA-10-tax-reporting-INTEGRATION.md - How other modules connect