QuickBooks Desktop and Adobe Commerce integration

What moves between them

The flow runs from Adobe Commerce into QuickBooks Desktop. ml-connector reads placed orders, their customers, and captured invoices from Adobe Commerce, then creates or updates the matching customer, posts a sales invoice, and records the received payment in QuickBooks Desktop, with product SKUs mapped to QuickBooks items so each line hits the right account. Credit memos from Adobe Commerce can post as the corresponding credit in QuickBooks. Because QuickBooks Desktop is the system of record for accounting, ml-connector treats it as the destination and does not push ledger entries back into the storefront. Reads from Adobe Commerce run on a schedule, or on webhook events where they are enabled, while writes into QuickBooks Desktop are queued for the next Web Connector cycle.

How ml-connector handles it

ml-connector stores both credential sets encrypted. For Adobe Commerce it signs OAuth 1.0a requests on PaaS or refreshes the IMS OAuth 2.0 token before its roughly 24-hour expiry on the Cloud Service, and it pages through orders and invoices using searchCriteria with total_count to know when it has read everything. On the QuickBooks side it implements the Web Connector SOAP methods, validates the session ticket on every call, and hands back QBXML Add requests for the Web Connector to relay into QuickBooks while the company file is open. Adobe Commerce increment_id values are stored against the QuickBooks TxnID and ListID so an order is never posted twice, since QuickBooks has no idempotency of its own. New customers are added before their invoices, and a stored EditSequence is re-queried before any Mod so concurrent edits are not overwritten. Large reads are split with searchCriteria paging on the Commerce side and QBXML iterators with MaxReturned on the QuickBooks side to stay under the roughly 60-second per-request timeout. Because there is no push from QuickBooks Desktop and the company file must be open for the Web Connector to run, sync is near-real-time on the inbound Commerce side and as frequent as the Web Connector interval on the QuickBooks side. Failed writes are retried and carry a full audit trail.

A real-world example

A mid-sized specialty retailer sells through an Adobe Commerce storefront and keeps its books in QuickBooks Desktop Enterprise on a Windows machine in the back office. Before the integration, a bookkeeper exported the day's web orders and typed each customer, invoice, and payment into QuickBooks by hand, which fell behind during busy weeks and left the sales accounts out of step with the store. With QuickBooks Desktop and Adobe Commerce connected, each placed order and captured invoice flows into QuickBooks as a customer, an invoice, and a received payment against the matching item, so the ledger reflects the storefront the same day and the manual entry step is gone.

What you can do

• •Create or update QuickBooks Desktop customers from Adobe Commerce buyers so each storefront order has a matching customer record.
• •Post Adobe Commerce orders and captured invoices into QuickBooks Desktop as sales invoices and received payments without re-keying.
• •Map Adobe Commerce product SKUs to QuickBooks Desktop items so every invoice line posts to the right account.
• •Bridge Adobe Commerce OAuth and the QuickBooks Web Connector session ticket, refreshing the IMS token before it expires.
• •Guard against duplicates by storing Adobe Commerce increment_id against the QuickBooks TxnID, with retries and a full audit trail.

Questions

Which direction does data move between QuickBooks Desktop and Adobe Commerce?

The flow runs from Adobe Commerce into QuickBooks Desktop. Orders, customers, and captured invoices move from the storefront into accounting as customers, sales invoices, and received payments. QuickBooks Desktop is the system of record for the ledger, so ml-connector does not push financial entries back into Adobe Commerce.

How does the integration reach QuickBooks Desktop if it has no cloud API?

QuickBooks Desktop is a local Windows product reached through the QuickBooks Web Connector, which polls a remote SOAP service on a set interval. ml-connector implements that SOAP service, authenticates with the Web Connector session ticket, and hands back QBXML Add requests for the Web Connector to relay into QuickBooks. QuickBooks must be running with the company file open for the Web Connector to process the work.

How are duplicate orders avoided when QuickBooks has no idempotency key?

QuickBooks Desktop does not deduplicate requests, so sending the same Add twice creates two records. ml-connector stores each Adobe Commerce increment_id against the QuickBooks TxnID or ListID returned on success and checks it before posting, so an order or invoice is only ever created once. BullMQ job dedup adds a second guard on the connector side.