QuickBooks Online and SFTP / Flat Files integration

What moves between them

Outbound: ml-connector reads bills, invoices, and vendor records from QuickBooks Online via REST and deposits them onto the SFTP server as CSV or X12 EDI files in the outbound folder on a schedule or on webhook trigger. Inbound: ml-connector polls the SFTP inbound folder, reads vendor bills or GL transactions from CSV or EDI files, and posts them into QuickBooks Online as bills, journal entries, or vendor credits, mapped to the matching QuickBooks accounts and classes. Acknowledgment files are produced and placed in the acks folder after each inbound transaction is processed.

How ml-connector handles it

ml-connector handles OAuth 2.0 token refresh for QuickBooks Online, re-authenticating when access tokens expire at the 1-hour mark. On the QuickBooks side, it reads the realm_id from your OAuth callback and uses it in every API call to ensure you are writing to the correct company. It accepts both webhook events (for near-real-time syncs) and polling via the CDC endpoint for systems with longer latency tolerance. On the SFTP side, ml-connector supports both SSH key-based authentication (recommended) and username-password, validates the host key to prevent MITM attacks, and polls on your specified schedule. When posting records back into QuickBooks Online, it maps SFTP file columns to QuickBooks accounts, classes, vendors, and customers, and it includes the SyncToken in every update to handle optimistic concurrency. It produces X12 997 acknowledgments after processing EDI files. QuickBooks webhook payloads contain only entity ID and operation, so ml-connector immediately fetches the full record via GET to capture all fields, and it deduplicates inbound files using file hash to prevent re-processing of duplicates on retry.

A real-world example

A small manufacturing business uses QuickBooks Online for accounting and must exchange bills and inventory receipts with a legacy ERP system that only accepts flat files over SFTP. Before the integration, the accounting team downloaded bills from QuickBooks, exported them as CSV, and uploaded them to the legacy system by hand each week. Vendor invoices arrived on the SFTP server in fixed-width format and had to be manually keyed into QuickBooks. With QuickBooks Online and SFTP / Flat Files connected, bills flow from QuickBooks to the legacy system as CSV every Monday, and inbound vendor invoices are automatically posted back into QuickBooks as bills under the correct vendor and GL account, eliminating two manual steps per week.

What you can do

• •Read bills, invoices, vendors, accounts, and class structures from QuickBooks Online and deposit them as CSV or X12 EDI files on your SFTP server on a defined schedule.
• •Poll your SFTP inbound folder, read vendor bills or GL transactions from CSV or EDI files, and post them into QuickBooks Online as bills, journal entries, or vendor credits mapped to matching accounts.
• •Handle OAuth 2.0 token refresh and SyncToken management so QuickBooks Online authentication and concurrency control are transparent and automatic.
• •Produce X12 997 or EDIFACT CONTRL acknowledgment files after processing inbound EDI transactions and place them in the acs folder.
• •Detect and skip duplicate files using hash-based deduplication so file retries do not cause duplicate postings in QuickBooks Online.

Questions

Which direction does data move between QuickBooks Online and SFTP / Flat Files?

Both directions. Bills, invoices, vendors, and accounts flow out from QuickBooks Online to your SFTP server as CSV or EDI files on a schedule or webhook trigger. Vendor bills and GL transactions flow inbound from SFTP files into QuickBooks Online as bills, journal entries, and vendor credits. QuickBooks webhook payloads trigger near-real-time syncs; polling via the CDC endpoint is available for less frequent updates.

How does ml-connector handle QuickBooks OAuth token refresh?

ml-connector tracks the 1-hour access token expiry and automatically refreshes using the refresh token before it expires. It stores the realm_id from your OAuth callback and includes it in every API call so records are posted to the correct QuickBooks company. Refresh tokens rotate every 24 to 26 hours, and ml-connector handles that rotation automatically.

What happens if I retry an inbound file and it is already in QuickBooks Online?

ml-connector uses file hash-based deduplication to detect and skip files that have already been processed. This prevents duplicate vendor bills or GL entries from being created on retry. Inbound files are logged with their hash in the audit trail so you can see which files have been received and when.