🔗 QuickBooks Online Connection

OAuth 2.0 Authentication: Secure, industry-standard OAuth 2.0 authorization flow for connecting your WordPress site to any QuickBooks Online company file without storing raw credentials.
Token Lifecycle Management: Automatic access token refreshing and persistent encrypted storage ensure the connection stays alive without manual re-authentication.
Sandbox & Production Support: Seamlessly toggle between QuickBooks Sandbox for testing and the live Production environment from a single settings toggle.
Connection Status Dashboard: Real-time connection health indicator in the admin showing authorization state, realm ID, and last successful sync timestamp.

🧾 Invoice Synchronization

One-Click & Bulk Sync: Sync individual invoices from the invoice builder or run batch synchronization across all unsent, failed, or selected invoices from the admin dashboard.
Idempotent Sync Engine: A lock-based idempotency system prevents duplicate invoices in QuickBooks even if a sync is triggered multiple times or interrupted mid-flight.
Canonical Data Model: All invoice data is normalized through a structured canonical model before transmission, ensuring consistent formatting regardless of how the invoice was created.
Line Item Mapping: Full line-item detail — descriptions, quantities, unit prices, and computed totals — is faithfully transmitted to QuickBooks for accurate financial records.
Multi-Currency Support: Invoices issued in non-base currencies are transmitted with the correct currency code, preserving multi-currency accounting in QuickBooks.
Status-Aware Filtering: Manual sync operations can be scoped by invoice status (draft, proforma, unpaid, partial, paid) or sync state (not yet synced, failed, all).

Automatic Customer Resolution: Before creating an invoice in QuickBooks, the plugin searches for an existing Customer record by email to prevent duplicates.
On-Demand Customer Creation: If no matching customer is found, a full QuickBooks Customer record is created automatically from invoice client data — name, email, phone, and billing address.
Customer ID Caching: Resolved QuickBooks Customer IDs are stored back on the WordPress invoice post, eliminating redundant lookups on future syncs.
Pre-Sync Client Validation: Invoices missing a client name or email are flagged with a clear, actionable error before any API call is made.

Per-Invoice Sync State: Each invoice carries a dedicated sync state record (pending, synced, failed) with the corresponding QuickBooks Invoice ID and sync token stored for update operations.
Detailed Sync Logs: Every sync attempt — success or failure — is logged with timestamp, direction, action type, and error message for full operational transparency.
Error Classification & Logging: Failures are categorized by error type (authentication, validation, API, network) and written to a structured error log with full exception context.
Admin Log Viewer: A dedicated Sync Logs admin page surfaces per-invoice sync history, error details, and resolution status without requiring database access.

QB Sync Column on Invoice List: A compact “QB Sync” column on both the WP admin All Invoices screen and the custom Invoice Dashboard shows live sync status with a tooltip displaying the QuickBooks Invoice ID.
Manual Sync Panel: A persistent admin UI panel lets administrators trigger targeted syncs filtered by invoice status and sync state, with a real-time results summary returned after each run.
Settings Page: Centralized configuration for API credentials, realm ID, sandbox mode, sync behavior defaults, and connection management — all in one dedicated screen.
Clear Log Controls: One-click log clearing for both sync logs and error logs directly from the admin interface.

Encrypted Token Storage: OAuth tokens are stored with encryption-at-rest rather than as plain text in the WordPress options table.
Nonce-Protected Admin Actions: All admin-triggered sync operations and settings changes are protected by WordPress nonce verification.
Input Sanitization & Validation: Every value entering or leaving the QB API is sanitized and validated against the canonical model before transmission.
Rate Limit & Lock Guards: Sync locks prevent race conditions during concurrent requests; API errors from QuickBooks are parsed and surfaced with human-readable messages.