FreeAgent

The FreeAgent integration is an accounting bridge for UK MSPs who run their books in FreeAgent. Invoices issued in OpsMerge push to FreeAgent; payments reconciled in FreeAgent flow back to OpsMerge as paid status.

It sits alongside QuickBooks Online and Xero as one of OpsMerge's accounting integrations. You connect one accounting package per tenant at a time, see One accounts package at a time.

What syncs

• Invoice push: OpsMerge to FreeAgent. When an invoice is issued in OpsMerge, it pushes to FreeAgent as a draft invoice, then is marked as sent.
• Paid-status pull: FreeAgent to OpsMerge. When an invoice is reconciled as paid in FreeAgent, the matching OpsMerge invoice flips to paid (or partial) automatically.
• Daily reconciliation: a once-a-day worker compares OpsMerge and FreeAgent and catches anything the frequent poll missed.

We also offer a one-off import review at connect time, so you can adopt your existing FreeAgent contacts and income categories rather than re-keying them:

• Contacts to clients: FreeAgent contacts can be imported as OpsMerge clients.
• Income categories to services: FreeAgent income categories can be imported as OpsMerge services.

Both go through a review queue where you map, create, or skip each item. See Import review.

Prerequisites

• A FreeAgent account. If you bank with NatWest, RBS, Mettle, or Ulster Bank business banking, FreeAgent ships free as part of that banking package, so most UK MSPs on those banks already have one.
• An OpsMerge tenant with no other accounting package connected. If QuickBooks Online is connected, disconnect it first, see One accounts package at a time.
• Permission to manage integrations in OpsMerge.

How to connect

1. Settings to Integrations to FreeAgent to Connect.
2. Click Connect to FreeAgent.
3. OAuth into the FreeAgent screen and authorise OpsMerge.
4. You are redirected back. OpsMerge shows "Connected to: <Your FreeAgent company name>".
5. Pick a deposit bank account. OpsMerge asks which FreeAgent bank account you reconcile invoice payments into. Choose it now so it is on record for payment handling.

Once connected, run the import review and set your mappings before you push your first invoice.

Import review

Connecting does not silently overwrite anything. Instead, OpsMerge pulls your FreeAgent contacts and income categories into a review queue, and you decide what happens to each one.

For each item you can:

• Map it to an existing OpsMerge record (e.g. this FreeAgent contact is the same as this OpsMerge client).
• Create a new OpsMerge record from it (import the FreeAgent contact as a new client).
• Skip it (don't import this one at all).

The two queues:

• Contacts to clients: FreeAgent contacts becoming OpsMerge clients. Map the ones you already track in OpsMerge, create the ones you don't, skip personal or dormant contacts.
• Income categories to services: FreeAgent income categories becoming OpsMerge services. The mapping you set here is what later drives invoice lines, each pushed invoice line maps to a FreeAgent income category via its service or product, so getting these right up front saves push failures later.

You don't have to clear the whole queue in one sitting. Map what you need now, push invoices, and come back to the rest.

Invoice push

Once your services are mapped (or a default income category is set, see below), invoice push is automatic:

1. An OpsMerge invoice is issued.
2. A background worker pushes it to FreeAgent as a draft invoice.
3. OpsMerge then marks the FreeAgent invoice as sent.
4. FreeAgent confirms. The OpsMerge invoice records the FreeAgent invoice ID.

What gets sent per line:

• Each invoice line maps to a FreeAgent income category via its mapped service or product. If a line's service or product has no mapped category, OpsMerge uses the default income category you configured (if set).
• VAT is sent per line, so FreeAgent records the right VAT against each line rather than a single invoice-level figure.

Preflight and what to do if a push fails

Before pushing, OpsMerge runs a preflight check. The rule is simple: every invoice line must resolve to a FreeAgent income category, either because its service or product is mapped, or because a default income category is set.

If a line can't resolve a category, the push fails and the OpsMerge invoice records the error. To fix it:

1. Open the invoice that failed.
2. The error tells you which line (or service) is unmapped.
3. Either map that service or product to a FreeAgent income category (Settings to PSA to Services to Map), or set a default income category in the FreeAgent integration settings so unmapped lines have a fallback.
4. Retry the push from the invoice. Once the mapping is in place, the same invoice pushes cleanly.

A status banner at the top of the FreeAgent settings page tells you what's mapped and whether a default income category is set, so you can spot gaps before they bite at month-end.

Voiding invoices

When you void an OpsMerge invoice that has already pushed, OpsMerge sets the FreeAgent invoice to cancelled.

We never delete the FreeAgent invoice. Cancelling preserves the audit trail on both sides, the invoice still exists in FreeAgent, it's just marked cancelled and no longer counts as outstanding.

Paid-status sync (polled, not instant)

FreeAgent does not offer webhooks, so OpsMerge polls FreeAgent for payment status rather than being pushed to.

How it works:

1. A frequent poll checks recently pushed invoices for a paid or part-paid state in FreeAgent.
2. When an invoice is reconciled as paid in FreeAgent, OpsMerge flips the matching invoice to paid (or partial for a part payment) automatically.
3. A daily reconciliation pass sweeps everything to catch anything the frequent poll missed.

Because this is polling and not a webhook, paid status is not instant. There's a short lag between marking an invoice paid in FreeAgent and seeing it update in OpsMerge. This is expected, not a bug. If a payment still hasn't reflected after the daily reconciliation has run, that's worth investigating, see Common issues.

Payments are recorded against the deposit bank account you chose at connect time.

One accounts package at a time

A tenant can have one accounting package connected at a time. FreeAgent and QuickBooks Online (and Xero) are mutually exclusive.

• To connect FreeAgent while QuickBooks is connected: disconnect QuickBooks first, then connect FreeAgent.
• To go back to QuickBooks later: disconnect FreeAgent first, then connect QuickBooks.

This is deliberate. Pushing the same invoices into two accounting systems would double-book your revenue and make reconciliation a nightmare. One source of accounting truth per tenant.

When you disconnect FreeAgent, existing OpsMerge data stays put, the invoices are still there, they just no longer carry FreeAgent links.

Common issues

Invoice push fails with an unmapped-category error. A line's service or product isn't mapped to a FreeAgent income category and no default income category is set. Map the service (Settings to PSA to Services to Map) or set a default income category, then retry the push from the invoice.

Push succeeded but the invoice shows as draft in FreeAgent. OpsMerge pushes as draft, then marks as sent. If it's stuck on draft, the "mark sent" step failed after the create succeeded. Retry the push from the invoice, OpsMerge is safe to re-run and will reconcile rather than duplicate.

Paid in FreeAgent but still Open in OpsMerge. Paid status is polled, not instant, so allow for the poll interval first. If it's still Open after the daily reconciliation has run, check the integration is still connected and the invoice carries a FreeAgent invoice ID (Audit log to Push events). If the ID is missing, the original push didn't complete.

Can't connect FreeAgent, the connect button is unavailable. Another accounting package is connected. Disconnect QuickBooks Online (or Xero) first, see One accounts package at a time.

Voided invoice still shows as outstanding in FreeAgent. Voiding maps to FreeAgent cancelled. If it still shows outstanding, the void didn't push, re-void or check the sync log.

Next

• Billing & invoices — what's pushed to FreeAgent
• Recurring invoices — the engine producing most pushed invoices
• QuickBooks Online — the alternative accounting bridge