Tax Reports Documentation

Menu Location: Reports > Payments > Taxes > Tax Reports

Access Level: Manager / Administrator

Last Updated: 2026-03-01

---

Overview

The Tax Reports page provides comprehensive sales tax reporting broken down by state, city, county, and zip code. It generates detailed or summary views of tax collected across different jurisdictions for specified time periods.

Primary Functions:

• Generate summary or detailed tax reports by date range
• Break down tax collection by geographic jurisdiction
• View state, city, county, and zip-level tax totals
• Calculate actual vs expected tax rates
• Export order-level tax details for accounting

---

Page Layout

Header Section

• Page Title: Payments \ Taxes \ Tax Reports
• Force Update Button: Updates all tax records (admin only)
• Debug Button: Shows detailed calculation view (admin only)

Filter Controls (Top Section)

• From Date Picker: Start date for tax report period
• To Date Picker: End date for tax report period
• Report Type Dropdown: Summary, Detailed, or "Show ALL THE PLACES!"
• Build Tax Report Button: Generates report with selected parameters

Main Content Area

Summary View:

• Overview table with totals across all tax categories
• State-level breakdown table
• City-level breakdown table
• County-level breakdown table
• Zip code breakdown table (if enabled)

Detailed View:

• Order-by-order listing with individual tax amounts
• Shows each order's contribution to tax totals
• Links to individual order records

---

Report Types

Summary Report

What It Shows:

• Aggregate totals by tax jurisdiction
• Tax rate vs actual collected comparison
• Geographic distribution of tax collection

Tables Included:

1. Overall Summary: Order count, state tax, payment total, delivery fee, city tax, county tax, zip tax, product sales tax, box tax
2. By State: State, tax rate, total taxable, tax collected
3. By City: City name, tax rate, total taxable, tax collected, actual rate
4. By County: County name, tax rate, total taxable, tax collected, actual rate
5. By Zip (if enabled): Zip code, tax rate, total taxable, tax collected, actual rate

Detailed Report

What It Shows:

• Every individual order in the date range
• Order ID and delivery date for each record
• Tax amounts broken down by category
• Links to drill into specific orders

Columns Displayed:

• Order ID (clickable link)
• Deliver On date
• State Tax
• Payment Total
• Delivery Fee
• City Tax
• County Tax
• Zip Tax
• Individual Product Sales Tax
• Box Tax

Show ALL THE PLACES Report

What It Shows:

• Special Note: Despite the name, this actually shows sum of actual_total from order data
• Discovers all unique states and cities in order data
• Not a true tax report - uses order totals instead of tax amounts
• Useful for geographic distribution analysis

When to Use:

• Geographic market analysis
• Identifying all delivery locations
• Understanding order distribution by location

---

Report Data & Columns

Summary Table Columns

Column	Description	Calculation/Source
Order Count	Number of orders in period	COUNT of non-cancelled orders
State Tax	Total state-level sales tax	SUM of state_tax from cust_order
Payment Total	Total customer payments	SUM of payment_total from cust_order
Delivery Fee	Total delivery charges	SUM of delivery_fee from cust_order
City Tax	Total city-level sales tax	SUM of city_tax from cust_order
County Tax	Total county-level sales tax	SUM of county_tax from cust_order
Zip Tax	Total zip code sales tax	SUM of zip_tax from cust_order
Individual Product Sales Tax	Tax on add-on items	SUM of order_prod_sales_tax
Box Tax	Tax on subscription boxes	SUM of order_box_tax

Geographic Breakdown Columns

Column	Description	Details
State/City/County/Zip	Jurisdiction name	From tax configuration tables
Tax Rate	Configured tax rate	Percentage from tax tables
Total Taxable	Amount subject to tax	Payment total minus already-taxed amounts
Tax Collected	Actual tax amount collected	From order records
Actual Rate	Calculated effective rate	(Tax Collected / Total Taxable) × 100

---

Filters & Search Options

Date Range Selection

From Date:

• Manual entry or calendar picker
• Required field for report generation
• Converted to Unix timestamp for queries

To Date:

• Manual entry or calendar picker
• Required field for report generation
• Converted to Unix timestamp for queries

Important Notes:

• Date range is inclusive of both start and end dates
• Filters by deliver_on field from orders
• Excludes cancelled orders (status != 5)

Report Type Selection

Summary (Default):

• Most common selection
• Shows aggregated totals by jurisdiction
• Best for monthly/quarterly reporting
• Easier to read and analyze

Detailed:

• Order-by-order breakdown
• Shows individual order tax calculations
• Useful for auditing specific transactions
• Helpful for investigating discrepancies

Show ALL THE PLACES:

• Geographic distribution analysis
• Shows all distinct states and cities
• Note: Uses actual_total, not tax amounts
• Useful for market expansion planning

---

Common Use Cases

Use Case 1: Monthly Tax Filing Preparation

Goal: Generate tax totals for monthly state/local filing

Steps:

1. Enter first day of month in From date
2. Enter last day of month in To date
3. Select "Summary" report type
4. Click "Build Tax Report"
5. Review state-level totals
6. Note city and county totals for local filings
7. Cross-reference with accounting records

Example: For March 2026 filing: From 03/01/2026, To 03/31/2026. Check state tax total matches accounting system before filing.

Tips:

• Run report a few days after month-end to ensure all orders processed
• Compare Total Taxable to gross sales for validation
• Verify tax rates match current jurisdiction rates

Use Case 2: Quarterly Tax Audit

Goal: Audit tax calculation accuracy for the quarter

Steps:

1. Set From date to quarter start (e.g., 01/01/2026)
2. Set To date to quarter end (e.g., 03/31/2026)
3. Select "Detailed" report type
4. Click "Build Tax Report"
5. Review individual order tax amounts
6. Click order IDs to investigate anomalies
7. Check Actual Rate columns for discrepancies

Tips:

• Look for orders where Actual Rate differs from Tax Rate by more than 0.02%
• Investigate orders with zero tax in taxed jurisdictions
• Verify payment totals match order summaries

Use Case 3: New Jurisdiction Tax Setup Verification

Goal: Confirm new city/county tax configuration works correctly

Steps:

1. Set date range to after tax implementation date
2. Select "Summary" report type
3. Click "Build Tax Report"
4. Scroll to City or County breakdown section
5. Find the new jurisdiction in the table
6. Verify Tax Rate column shows correct percentage
7. Confirm Actual Rate matches configured Tax Rate (within 0.02%)
8. If mismatch, use "Force Update All Tax Records" (admin only)

Example: After adding 2.5% tax for Springfield city, verify Actual Rate shows 2.50% (or very close).

Use Case 4: Geographic Market Analysis

Goal: Understand where most orders come from for expansion planning

Steps:

1. Set From date to 1 year ago
2. Set To date to today
3. Select "Show ALL THE PLACES!" report type
4. Click "Build Tax Report"
5. Review By State table for state distribution
6. Review By City table for city concentration
7. Identify underserved markets with low order counts

Tips:

• Remember this uses actual_total, not tax amounts
• Higher totals indicate stronger market presence
• Use for marketing budget allocation

Use Case 5: Tax Compliance Verification

Goal: Ensure all required tax is being collected

Steps:

1. Set date range to review period
2. Run "Summary" report first for overview
3. Check each jurisdiction section
4. Verify no jurisdiction shows 0% Actual Rate if tax required
5. Switch to "Detailed" report
6. Identify any orders with zero tax in taxed areas
7. Investigate and correct tax configuration if needed

Example: If California shows 7.5% Tax Rate but 0% Actual Rate, tax calculation may be broken for that state.

---

Actions & Operations

Build Tax Report

Purpose: Generates tax breakdown with current date and report type settings

Steps:

1. Select From and To dates
2. Choose report type (Summary/Detailed/ALL THE PLACES)
3. Click "Build Tax Report" button
4. Review generated tables and totals

Notes:

• Report generation may take 10-30 seconds for large date ranges
• Detailed reports with thousands of orders can be slow
• System excludes cancelled orders automatically

Force Update All Tax Records (Admin Only)

Purpose: Recalculates all tax amounts in database

Steps:

1. Only visible if logged in as 'wayne' or on dev server
2. Click "Force Update All Tax Records" button
3. Confirm the action in popup dialog
4. System recalculates tax for all orders
5. Session message confirms completion

When to Use:

• After changing tax rates for past orders
• After fixing tax calculation bugs
• After importing historical data
• When tax totals don't match expectations

Warning:

• This operation can take several minutes
• May timeout on very large databases
• Run during off-peak hours if possible

---

Troubleshooting

Tax Totals Don't Match Accounting Records

Symptoms: Report shows different totals than accounting software

Check:

1. Verify date range matches accounting period exactly
2. Confirm both systems use same timezone
3. Check if accounting includes cancelled orders (report excludes them)
4. Verify payment_total field matches accounting revenue
5. Ensure order status filtering is consistent

Solutions:

1. Use exact date boundaries (start of day to end of day)
2. Cross-reference order counts between systems
3. Run Detailed report to audit specific discrepancies
4. Contact Kiva Logic if persistent differences exist

Common Causes:

• Different date range interpretations
• Including vs excluding cancelled orders
• Timezone differences in timestamps
• Refunds or credits not reflected consistently

City or County Shows Wrong Tax Rate

Symptoms: Configured rate doesn't match actual collected rate

Check:

1. Verify tax configuration in Settings > Tax Settings
2. Check if rate changed mid-period (causes mixed rates)
3. Look for orders before/after rate change
4. Verify city/county name spelling matches exactly

Solutions:

1. Update tax configuration for jurisdiction
2. Use "Force Update All Tax Records" to recalculate
3. For mid-period changes, run separate reports before/after
4. Verify tax_cities and tax_counties tables have correct rates

If Problem Persists: Contact Kiva Logic support with jurisdiction name and expected vs actual rates.

Missing Orders in Detailed Report

Symptoms: Known orders from date range don't appear in detailed view

Check:

1. Verify order status is not 5 (cancelled)
2. Confirm deliver_on date is within selected range
3. Check if order has tax amounts recorded
4. Verify order ID by searching directly

Solutions:

1. Expand date range to include order's actual delivery date
2. Check order details page for delivery date and status
3. Ensure order was actually delivered (not pending/cancelled)
4. Run database query to verify order exists

Zip Tax Section Not Showing

Symptoms: Report doesn't include "By Zip" breakdown table

Check:

1. Verify getConfig('enable_zip_tax') is true
2. Confirm zip tax is enabled in system settings
3. Check if date range is selected (zip section requires dates)

Solutions:

1. Enable zip tax in Settings if needed
2. Ensure $start and $end variables are set
3. Contact admin to enable zip tax functionality

---

Related Pages

• Tax Settings (settings-taxes.php) - Configure tax rates by jurisdiction
• Tax Cities (tax-cities.php) - Manage city-level tax configuration
• Tax Counties (tax-counties.php) - Manage county-level tax configuration
• Payment Transactions (billing-payments.php) - View payment-level details
• Order Details (customer_order_info.php) - Individual order tax breakdown

Typical Workflow:

1. Tax Reports → Identify discrepancy → Tax Settings → Update rate → Force Update Records
2. Tax Reports → Monthly summary → Export → File with jurisdiction
3. Order Details → Check tax calculation → Tax Reports → Verify jurisdiction totals

---

Permissions & Access

Required Access Level: View access (implied - no explicit permission check in code)

Access Level Capabilities:

• Customer Service: View reports for customer inquiries
• Manager: View and generate tax reports
• Administrator: Full access to all report types
• Kiva Admin: All features plus Force Update and debug tools (username 'wayne')

Restricted Features:

• Force Update All Tax Records: Kiva Admin only
• Debug view: Kiva Admin only (show_all parameter)

---

Best Practices

Regular Reporting

1. Generate monthly reports within 3 days of month-end
2. Run quarterly audits using Detailed view
3. Keep PDF copies of monthly reports for compliance
4. Compare month-over-month for unusual changes

Tax Rate Verification

1. Check Actual Rate vs Tax Rate monthly
2. Investigate any variances over 0.02%
3. Update jurisdiction rates promptly when changed
4. Document rate changes with effective dates

Audit Trail

1. Archive monthly summary reports
2. Keep detailed reports for audited periods
3. Document any manual tax adjustments
4. Note jurisdiction changes in a log

Things to Avoid

• ❌ Don't use "Show ALL THE PLACES" for actual tax filing - it shows totals, not taxes
• ❌ Don't forget to exclude cancelled orders in manual calculations
• ❌ Don't run Force Update during peak business hours
• ❌ Don't assume tax configuration hasn't changed mid-period

---

Quick Reference Card

Task	Action/Location
Monthly tax filing	From/To = month dates, Summary report
Audit tax accuracy	Detailed report, check Actual vs Tax Rate
Verify new jurisdiction	Summary report, find city/county in tables
Geographic analysis	"Show ALL THE PLACES" report type
Fix tax discrepancies	Force Update All Tax Records (admin)
Check order tax	Detailed report, click Order ID
View state totals	Build report, scroll to "By State" table
Calculate quarterly tax	Set From/To to quarter dates
Export tax data	Use browser print-to-PDF
See zip code taxes	Enable zip tax, build Summary report

---

FAQs

Why does the "Show ALL THE PLACES" report show different numbers than Summary?

This report type uses actual_total (order totals) instead of tax amounts. It's designed for geographic distribution analysis, not tax reporting. Use Summary or Detailed for actual tax filing.

What's the difference between order_prod_sales_tax and box_tax?

order_prod_sales_tax is tax on add-on items purchased individually. box_tax is tax on the subscription box itself. They're calculated separately because some jurisdictions tax them differently.

Can I export this data to Excel or QuickBooks?

The page doesn't have a built-in export button. Use your browser's print function to create a PDF, or copy the table data and paste into Excel. For QuickBooks integration, contact Kiva Logic about custom export formats.

Why do some cities show an "Actual Rate" different from "Tax Rate"?

This can happen when the tax rate changed mid-period, when there are rounding differences in calculations, or when tax configuration doesn't match actual collection. Investigate discrepancies over 0.02%.

How often should I run the Force Update function?

Only when specifically needed after tax configuration changes or when investigating discrepancies. It's not a routine operation. Most sites never need to use it.

---

Change Log

2026-03-01

• Initial documentation created
• All sections completed based on tax-report.php code review
• Documented three report types in detail
• Included Force Update functionality
• Added geographic breakdown table explanations

---

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.