QuickBooks Desktop and Square integration

What moves between them

Payments and refunds flow from Square into QuickBooks Desktop. ml-connector polls Square on a daily or weekly schedule for all payments and refunds since the last sync, then translates each payment into a QB customer deposit or invoice payment, and each refund into a QB credit memo. Order records from Square can also be synced if they map to QB customers. All transactions are tagged with their Square payment ID in QB to prevent duplicates on re-sync.

How ml-connector handles it

ml-connector stores your Square access token encrypted and refreshes it before expiry using the refresh token. On the QB Desktop side, it initiates a SOAP session with the Web Connector by calling the authenticate() method with the QBWC credentials, receives a session token, and uses that token for all subsequent QBXML queries. Because QB Desktop has no webhooks and the QBWC agent operates sequentially with a 60-second timeout, ml-connector batches Square payment records and posts them in sized chunks so each QBXML request stays under the timeout. Square payments are mapped to QB customers by matching email address or phone number; unmapped transactions are logged for manual review. Refunds are posted as credit memos against the original QB invoice. EditSequence version numbers are re-queried before any QB update to prevent concurrent edit conflicts.

A real-world example

A small retail store uses Square for point-of-sale and payments and QuickBooks Desktop for bookkeeping. Before the integration, the owner exported Square sales reports daily, opened QB, and manually created deposit records and customer invoices by hand. This was tedious, error-prone, and delayed closing the books each month. With QuickBooks Desktop and Square connected via ml-connector, every Square payment automatically appears in QB as a customer invoice or bank deposit, tagged with the Square transaction ID. The owner opens QB to a fully populated payment list, matches deposits to QB bank transactions, and closes the books with no manual re-entry step.

What you can do

• •Post Square payments into QuickBooks Desktop as customer invoices or bank deposits, mapped to the correct QB customer and account.
• •Sync Square refunds as QB credit memos tied to the original invoice so reconciliation tracks the full transaction lifecycle.
• •Map Square customers to QB customers by email or phone number, creating new QB customer records where needed.
• •Refresh Square access tokens before expiry and manage the SOAP session token with the QB Web Connector to ensure uninterrupted polling.
• •Run on a daily or weekly schedule with full audit trail and error replay if a payment sync fails.

Questions

Does the integration require any special setup on my QuickBooks Desktop machine?

Yes. The customer-hosted QBWC Web Connector must be installed and running on the Windows machine where QuickBooks Desktop is open. ml-connector connects to your endpoint URL via SOAP, and QBWC calls it on a configurable polling interval. QuickBooks must be logged into the company file and running in the background for the Web Connector to process requests.

Which direction does data flow between QuickBooks Desktop and Square?

The main flow is Square into QuickBooks Desktop. Payments and refunds move from Square into QB as invoices, deposits, and credit memos. Order records can also sync if they map to QB customers. QB customer and account data is read to identify where Square transactions should post, but QB data does not push back to Square.

How does ml-connector handle Square's 30-day access token expiry?

ml-connector stores your Square access token encrypted and tracks its expiry date. Before making any Square API call, it checks if the token is within 1 day of expiry and refreshes it using the refresh token if needed. This prevents outages due to token expiry and ensures continuous polling of Square payments and refunds.