Donations for WooCommerce QuickBooks Sync

Syncs WooCommerce donations to QuickBooks Online as Sales Receipts. Listens on Phase 9 hooks emitted by Donations for WooCommerce Companion.

Description

A sibling plugin for Donations for WooCommerce Companion. Sits downstream from the companion's Phase 9 event hooks (dfwc_companion_donation_submitted and friends) and creates a QuickBooks Online Sales Receipt for each donation as it lands.

How it works

Cash, stock, and (eventually) crypto donations all flow through the same pipeline:

1. Donor completes a donation through the companion's donor form.
2. Companion fires dfwc_companion_donation_submitted after the donation is real (parent plugin success, stock pledge marked received, Overflow webhook arrives, etc.).
3. This plugin's listener catches the hook and enqueues a sync job onto Action Scheduler.
4. The async worker calls QuickBooks Online's REST API and creates a Sales Receipt against the campaign-mapped Income account.
5. On failure, the worker retries with exponential backoff (60s → 5m → 15m → giving up after 3 attempts).

Key features

• OAuth2 with admin-supplied app credentials. Each admin registers their own Intuit app at developer.intuit.com — no shared credentials, no app-review treadmill, no shared rate-limit pain.
• Encrypted token storage. AES-256-CBC at rest, key derived from AUTH_KEY . AUTH_SALT. Per-write random IV.
• Per-campaign account mapping. Each wc-donation campaign can route to a specific QuickBooks Income Account; unmapped campaigns fall through to a configurable default.
• Async retry queue. Action Scheduler-backed; survives traffic-starved sites and provides Tools → Scheduled Actions visibility for free.
• Diagnostics integration. Two health checks (qbo_connection, qbo_sync_health) appear on the companion's existing Diagnostics page — no separate UI to discover.
• CLI commands. wp dfwc-qbo status, wp dfwc-qbo sync --days=30, wp dfwc-qbo reset.
• Privacy-by-default. Aggregate-only data (campaign, amount, currency, context) reaches QuickBooks; donor PII never leaves your site.

Required plugins

• WooCommerce 5.0+
• Donation for WooCommerce 3.9.8+
• Donations for WooCommerce Companion 2.1.0+

Installation

1. Install and activate WooCommerce, Donation for WooCommerce, and Donations for WooCommerce Companion (all required).
2. Install and activate this plugin.
3. Register an Intuit app at developer.intuit.com → My Apps → Create an app → QuickBooks Online and Payments. Note the Client ID and Client Secret.
4. Register the redirect URI on your Intuit app: https://your-site.example/wp-json/dfwc-qbo-sync/v1/oauth-callback.
5. WP Admin → WooCommerce → QuickBooks Sync → paste your Client ID + Secret → Save.
6. Click Connect to QuickBooks and complete the OAuth flow.
7. Map your campaigns to QuickBooks Income Accounts.
8. Toggle "Enable QuickBooks sync" on. Donations from this point forward sync automatically.

Frequently Asked Questions

Why a separate plugin from the companion?

Cleaner architecture. The companion's job is donor-form UX + emitting the Phase 9 event hooks. Anything that consumes those hooks (this plugin, future FluentCRM, GA4, Xero, Slack connectors) belongs separately.

I was on companion v2.0.x when QBO was bundled — will my data carry over?

Yes. Encrypted tokens, account mappings, and the existing sync log all use the same option keys, so installing this plugin + upgrading companion to v2.1.0 carries everything over with no reconnection required. A one-line "Migrated" entry appears in the sync log.

Does this support Xero / FreshBooks / Wave?

No, just QuickBooks Online. Companion's Phase 9 hooks are the integration seam — a separate plugin could implement Xero sync against the same hooks.

Can I see what's been synced?

WP admin → WooCommerce → QuickBooks Sync → Recent activity panel shows the last 50 attempts. Each successful sync's "Message" column shows the QBO Sales Receipt ID for direct lookup in QuickBooks.

What happens if a sync fails?

The retry queue automatically retries 3 times with 60s → 5m → 15m backoff. If all retries fail, the entry shows as failed in the sync log. Causes are usually invalid account mappings, expired tokens, or QBO downtime.

Privacy

This plugin sends only aggregate donation data (campaign title, amount, currency, transaction date) to QuickBooks. Donor names, emails, addresses, and other PII never leave your site. The PrivateNote field of each Sales Receipt contains dfwc-qbo-sync campaign=<id> context=<ctx> for reconciliation purposes.

Compatibility

• PHP 7.4+ (8.3 tested)
• WordPress 6.2+ (6.7 tested)
• WooCommerce 5.0+ (10.2 tested)
• Donations for WooCommerce Companion 2.1.0+

Changelog

1.0.0

First release. Migrated from Donations for WooCommerce Companion v2.0.x where this functionality originally shipped (Phase 15). Architecture unchanged; namespace renamed from DFWC\Companion\QuickBooks\* to DFWC\QboSync\*. Existing sites carry over tokens, mappings, and sync log without reconnection.

• OAuth2 with admin-supplied Intuit app credentials.
• AES-256-CBC encrypted token storage (key derived from AUTH_KEY).
• Per-campaign QBO Income Account mapping.
• Action Scheduler-backed async retry queue (60s → 5m → 15m backoff; 3 max retries).
• Two diagnostic checks injected into companion's Diagnostics page (qbo_connection, qbo_sync_health).
• CLI: wp dfwc-qbo status, wp dfwc-qbo sync --days=30 [--campaign=<id>] [--dry-run], wp dfwc-qbo reset.
• Filter dfwc_qbo_sync_payload for customizing the Sales Receipt body. Companion's legacy dfwc_companion_qbo_payload filter is also applied for backward-compatibility with listeners written for companion v2.0.x.
• One-time migration on first activation: copies qbo_* settings out of dfwc_companion_global_settings into this plugin's own dfwc_qbo_sync_settings option.

Upgrade Notice

1.0.0

First release. Migration from companion v2.0.x is automatic — install this plugin, upgrade companion to v2.1.0, and existing tokens / mappings / sync log carry over with no reconnection required.