TaxDebug for WooCommerce

توضیحات

TaxDebug for WooCommerce helps store owners debug, understand, trust, and report their taxes – especially when using WooCommerce Tax (automated taxes) or other tax calculation services.

Key Features

Deep Tax Visibility
* See exactly how taxes were calculated for every order
* View applied tax rates, line-item breakdowns, and calculation formulas
* Understand which service/plugin produced each tax amount (WooCommerce Core, WooCommerce Tax, TaxJar, Avalara)

Issue Detection Engine
* Automatically detect common tax problems:
* No tax collected where expected
* Tax charged in non-taxable regions
* Rate mismatches vs reference rates
* Missing local (county/city) taxes
* Tax changes between cart and checkout
* Suspected API errors

Beautiful Dashboard & Reports
* Modern, responsive admin interface
* Interactive charts showing tax by state, country, and over time
* KPI cards for total tax, taxable sales, and effective rates
* Powerful filtering by date, country, state, tax source, and more

Order Explorer
* Search and filter all orders with tax data
* View detailed tax debug information for any order
* Identify orders with detected issues quickly

Accountant-Friendly Exports
* Export summary reports by country/state
* Export detailed order-level tax breakdowns
* Export detected issues for review
* CSV format compatible with Excel and accounting software

Safe & Non-Intrusive
* Does NOT modify how taxes are calculated
* Only observes, logs, and analyzes tax data
* Works with any tax calculation method

Feedback & Analytics
* In-app feedback widget to report false positives/negatives
* Feature request and success story submissions
* Privacy-first usage analytics (all data stored locally)
* Deactivation survey to help improve TaxDebug
* All feedback stored locally – no external tracking

Compatibility

TaxDebug works with:
* WooCommerce Core tax rates
* WooCommerce Tax (automated taxes via TaxJar)
* TaxJar plugin
* Avalara AvaTax
* Other tax plugins

Requirements

• WordPress 5.8 or higher
• WooCommerce 5.0 or higher
• PHP 7.4 or higher

Privacy

TaxDebug stores order tax data locally in your WordPress database. This includes:
* Order IDs and dates
* Customer billing/shipping addresses (country, state, city, postcode only)
* Order totals and tax amounts
* Tax calculation details

TaxDebug does NOT:
* Store payment information
* Store full customer names or personal details beyond address location

Data retention can be configured in Settings. You can also manually clear all logs at any time.

Feedback Collection

TaxDebug collects optional feedback to improve the plugin:

• In-app feedback: Report false positives, false negatives, feature requests, or success stories
• Usage analytics: Anonymous local tracking of which features are used
• Deactivation survey: Optional one-question survey when deactivating

Local Storage: All feedback is always stored locally in your WordPress database.

Optional Remote Sending: You can opt-in to send anonymous feedback to the developer to help improve TaxDebug. This is disabled by default and must be explicitly enabled in Settings.

What IS Sent (When Opted-In)

• Anonymous store UUID (random identifier, NOT your domain)
• Feedback type and message
• Your email (only if you voluntarily provide it)
• Store country and currency
• Active tax plugin (e.g., TaxJar, Avalara)
• Plugin, WordPress, and WooCommerce versions
• Daily aggregated counts: orders logged, issues detected, features used

What is NEVER Sent

• Your site URL or domain name
• Customer names, emails, or addresses
• Order details, totals, or line items
• Tax amounts or financial data
• Any personally identifiable information (PII)

How to Disable Remote Sending

Go to WooCommerce → TaxDebug → Settings and turn off “Send Anonymous Feedback”. You can do this at any time. Local feedback storage will continue to work.

Developer Notes

Hooks & Filters

TaxDebug provides several hooks for extensibility:

Actions:
* taxdebug_loaded – Fired when TaxDebug is fully loaded
* taxdebug_order_logged – Fired when an order is logged (params: log_id, order_id, payload)
* taxdebug_installed – Fired on plugin installation
* taxdebug_logs_cleaned_up – Fired when old logs are cleaned up

Filters:
* taxdebug_order_payload – Filter the order payload before logging
* taxdebug_detected_issues – Add custom issue detection rules

REST API Endpoints

TaxDebug provides a REST API under the taxdebug/v1 namespace:

• GET /logs – Get tax logs with filtering
• GET /logs/{id} – Get single log
• GET /logs/order/{order_id} – Get log by order ID
• POST /logs/reanalyze/{order_id} – Re-analyze an order
• GET /issues – Get detected issues
• GET /stats/dashboard – Get dashboard statistics
• GET /stats/chart/time – Get time series chart data
• GET /stats/chart/state – Get tax by state data
• GET /stats/chart/country – Get tax by country data
• GET /export/summary – Export summary CSV
• GET /export/detailed – Export detailed CSV
• GET /export/issues – Export issues CSV

All endpoints require manage_woocommerce capability.

Database Tables

TaxDebug creates two custom tables:

• {prefix}taxdebug_logs – Stores order tax log data
• {prefix}taxdebug_issues – Stores detected issues
• {prefix}taxdebug_feedback – Stores user feedback submissions
• {prefix}taxdebug_analytics – Stores usage analytics
• {prefix}taxdebug_error_logs – Stores internal error logs

WP-CLI Commands

(Coming in future versions)