Which direction do records move between FreshBooks and Square?

Payment and invoice records flow primarily from Square into FreshBooks. When Square processes a payment or creates an invoice, ml-connector reads that record and creates a matching entry in FreshBooks under the correct client. Refunds in Square become payment reversals in FreshBooks. Customer records are synchronized in both directions to keep the two systems aligned.

How does ml-connector handle FreshBooks OAuth authentication?

ml-connector uses FreshBooks' user-delegated OAuth 2.0 Authorization Code grant, the only OAuth flow FreshBooks supports for third-party integrations. It stores the access token securely and refreshes it when needed. For Square, it stores the Bearer access token and refreshes it before the 30-day expiry window to prevent authentication failures.

Why does ml-connector both receive webhooks and poll both systems?

FreshBooks and Square webhooks can be delayed or missed due to network conditions or system load. ml-connector receives webhooks for real-time notification but also runs periodic polling to catch any records not delivered by webhook and to verify consistency between the two systems.

FreshBooksSquare

FreshBooks and Square integration

FreshBooks manages your accounting, invoicing, and expense tracking. Square handles your payments and point-of-sale transactions. Connecting them means your payments settle in Square and post automatically to FreshBooks, keeping your accounting ledger current without manual data entry. Invoices you issue in FreshBooks can be tracked in Square, and Square's payment records become FreshBooks payment entries matched to the correct client and invoice. The two systems stay aligned on every transaction.

How FreshBooks works

FreshBooks exposes invoices, bills, payments, clients, expenses, chart of accounts, and items through REST APIs at https://api.freshbooks.com. Authentication uses OAuth 2.0 Authorization Code grant (user-delegated, not Client Credentials), with separate namespaces for accounting resources and time tracking. FreshBooks publishes webhook events for invoice, payment, bill, expense, and client lifecycle changes via POST to a customer-supplied endpoint, signed with HMAC-SHA256. Webhook delivery can range from seconds to several minutes, and retries are triggered by non-2xx responses or timeouts after 10 seconds. The platform does not expose standalone employee records; staff only appear as staffid fields on expenses. Chart of Accounts endpoints use a distinct business_uuid path pattern.

How Square works

Square exposes payments, invoices, orders, customers, vendors, inventory, and catalog through a versioned REST API at https://connect.squareup.com/v2, with a separate sandbox environment. Authentication uses OAuth 2.0 Authorization Code flow for multi-seller use or Personal Access Token for single-account access, both as Bearer tokens. Access tokens expire after 30 days and require refresh-token handling. Square supports webhook push notifications for payment, refund, invoice, order, customer, and inventory events with HMAC-SHA256 signature verification. The Vendors API is in beta. Square does not expose a general ledger or chart of accounts; it is a commerce-layer platform that requires mapping to external accounting systems.

What moves between them

Payment and invoice records flow from Square into FreshBooks. When Square processes a payment, ml-connector reads the payment record including amount, customer, date, and payment method, then creates a corresponding payment record in FreshBooks matched to the client and invoice. Invoices created in Square can also trigger FreshBooks invoice creation or updates. Reference data such as customer and vendor records are synchronized to keep the two systems aligned. Refunds in Square flow into FreshBooks as payment reversals. The sync runs on Square webhook events where available and polls on a schedule for completeness.

How ml-connector handles it

ml-connector stores OAuth 2.0 credentials securely for both FreshBooks and Square. For FreshBooks, it uses the user-delegated Authorization Code grant and manages token refresh. For Square, it presents the Bearer access token on every request and handles the 30-day token expiry by refreshing before the token becomes stale. ml-connector receives Square webhook notifications at a customer-supplied endpoint, validates signatures via HMAC-SHA256, and writes the payment or invoice record into FreshBooks. Because FreshBooks webhooks can be delayed, ml-connector also polls both systems on a schedule to catch any records missed by webhook delivery and to ensure consistency. When mapping Square payments to FreshBooks, ml-connector matches the customer in Square to the client in FreshBooks and links the payment to the correct invoice using the Square order or invoice reference. Every record includes a full audit trail, timestamp, and unique identifier so records can be replayed if a write to FreshBooks fails.

A real-world example

A small e-commerce or retail business uses Square at point-of-sale and online checkout for payment processing, and uses FreshBooks for accounting and invoicing. Before the integration, the business owner manually exported Square transactions from the Square dashboard each day and re-entered the payments into FreshBooks, a tedious and error-prone process that delayed month-end close and risked double-entry mistakes. With FreshBooks and Square connected, each payment is automatically captured from Square and posted to FreshBooks under the correct customer and invoice. The owner sees real-time cash positions and no longer needs to reconcile Square and FreshBooks balances by hand.

What you can do

Post Square payments into FreshBooks, automatically matched to the correct client and invoice.
Sync Square invoice records to FreshBooks invoicing and accounting ledger.
Reflect Square refunds as payment reversals in FreshBooks to keep transaction records aligned.
Authenticate Square Bearer tokens with automatic refresh before 30-day expiry and FreshBooks OAuth 2.0 user-delegated grants.
Receive Square webhook notifications, validate signatures, and poll both systems on schedule for completeness and audit.

Questions

Which direction do records move between FreshBooks and Square?: Payment and invoice records flow primarily from Square into FreshBooks. When Square processes a payment or creates an invoice, ml-connector reads that record and creates a matching entry in FreshBooks under the correct client. Refunds in Square become payment reversals in FreshBooks. Customer records are synchronized in both directions to keep the two systems aligned.
How does ml-connector handle FreshBooks OAuth authentication?: ml-connector uses FreshBooks' user-delegated OAuth 2.0 Authorization Code grant, the only OAuth flow FreshBooks supports for third-party integrations. It stores the access token securely and refreshes it when needed. For Square, it stores the Bearer access token and refreshes it before the 30-day expiry window to prevent authentication failures.
Why does ml-connector both receive webhooks and poll both systems?: FreshBooks and Square webhooks can be delayed or missed due to network conditions or system load. ml-connector receives webhooks for real-time notification but also runs periodic polling to catch any records not delivered by webhook and to verify consistency between the two systems.

Connect FreshBooks and Square

Free to use. Add your credentials, ping your real systems, and see if we fit.

Get started