FreshBooks and WooCommerce integration

What moves between them

Orders created in WooCommerce flow into FreshBooks as invoices, with the customer record created or updated in FreshBooks if needed, and each line item mapped to a FreshBooks item or service. Payments logged in FreshBooks flow back into WooCommerce to mark orders as paid or pending based on payment status. Both systems support webhooks, so ml-connector listens to WooCommerce order.created and order.updated events, and FreshBooks payment.create and payment.update events, and processes them on receipt rather than polling.

How ml-connector handles it

ml-connector stores the FreshBooks OAuth token and WooCommerce API Key credentials encrypted, and maintains the OAuth 2.0 token refresh cycle since FreshBooks issues time-limited access tokens. On the WooCommerce side, it presents the API Key via HTTP Basic Auth on every request. When a WooCommerce order webhook arrives, ml-connector parses the order line items, looks up or creates the matching FreshBooks client, and creates an invoice with lines mapped to FreshBooks items by SKU or description. Conversely, when a FreshBooks payment webhook arrives, ml-connector matches the payment to the corresponding WooCommerce order and updates the order status and order note to reflect payment received. Because both systems deliver webhooks asynchronously with no guaranteed ordering, ml-connector indexes each record by its external ID (WooCommerce order ID and FreshBooks invoice ID) to prevent duplicate invoices if a webhook retries. It handles WooCommerce's webhook re-enable requirement by surfacing disabled callbacks in the audit log. FreshBooks status fields are read-only (computed by the system), so ml-connector mirrors that constraint and does not attempt to override invoice or payment status directly.

A real-world example

A small e-commerce business runs WooCommerce on their own WordPress site and uses FreshBooks for invoicing and accounting. Before the integration, the owner manually created a FreshBooks invoice for each WooCommerce order at the end of each day, copy-pasting the customer name, order total, and line items, and then logged payments in FreshBooks separately when they confirmed payment in their bank account. This process was error-prone and delayed their ability to see real-time revenue and cash position. With WooCommerce and FreshBooks connected, each new order in the store becomes a FreshBooks invoice within seconds, the customer record is created or matched automatically, and payments confirmed in FreshBooks update the order status in WooCommerce. The owner now has an accurate, real-time view of sales and cash, and the manual invoice creation step is eliminated.

What you can do

• •Create FreshBooks invoices automatically from WooCommerce orders, with customer records and line items mapped correctly.
• •Update WooCommerce order status when payments are confirmed in FreshBooks, keeping sales records and cash tracking in sync.
• •Match WooCommerce customers to existing FreshBooks clients by email, or create new client records when a customer is not yet in the accounting system.
• •Map WooCommerce product SKUs and names to FreshBooks items or services, or create missing items on first use.
• •Manage OAuth 2.0 token refresh for FreshBooks and API Key authentication for WooCommerce, with full audit replay if a webhook fails to process.

Questions

How are WooCommerce orders mapped to FreshBooks invoices?

When a WooCommerce order webhook arrives, ml-connector extracts the customer email, order total, and line items. It looks up the matching FreshBooks client by email; if no match is found, it creates a new client with the order billing address. It then creates a FreshBooks invoice for that client with one line per order item, mapping the product SKU to a FreshBooks item or creating a new generic item if the SKU is not found.

What happens when a payment is confirmed in FreshBooks?

When a FreshBooks payment webhook arrives, ml-connector matches the payment amount and date to the corresponding WooCommerce order, then updates the order status to 'processing' or 'completed' depending on whether the full order amount has been paid. An order note is added to document the payment. If the payment amount does not match any open WooCommerce order, it is logged in the audit trail for manual review.

How does the integration handle OAuth 2.0 token expiry and WooCommerce webhook re-enablement?

ml-connector stores the FreshBooks OAuth token encrypted and refreshes it proactively before expiry using the refresh token provided at initial authorization. On the WooCommerce side, if five consecutive webhook deliveries return non-2xx responses, WooCommerce disables the webhook; ml-connector detects this in the audit log and surfaces an alert so the webhook can be re-enabled manually via the WooCommerce admin panel. Both failure modes are logged in the audit trail with the exact error for troubleshooting.