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. Don't have one yet? Start a 30-day free trial and enter code 4wkrd0ip when you subscribe for 10% off — if you're already mid-trial, you can still apply the code at subscribe time.
• 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.
• EU reverse charge is classified correctly. An invoice flagged reverse charge (or whose lines carry a reverse-charge tax code) is pushed with FreeAgent's post-Brexit Reverse Charge VAT status, so the sale is recorded outside the scope of UK VAT with the net in box 6 — not as domestic zero-rated revenue. Lines go out at 0%; a reverse-charge invoice with a positive-rate line fails preflight rather than pushing wrong VAT.
• Foreign-currency invoices push in their own currency (the invoice's currency is sent, e.g. EUR). Note FreeAgent contacts default to your account's home currency — set the contact's currency in FreeAgent itself if you want its contact-level view to match.
• The invoice number matches. OpsMerge sends its own invoice number as the FreeAgent invoice reference, so the same number appears in both systems. (FreeAgent's own sequential-number suggestion stops tracking once it sees a non-numeric reference — that's expected, since OpsMerge is now the source of the number.)

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.

OpsMerge owns the customer emails

OpsMerge sends your invoice emails, so a pushed invoice never triggers FreeAgent's own emails. OpsMerge explicitly switches off FreeAgent's new-invoice, payment-reminder, and thank-you emails on every invoice it pushes, so your customers don't get two of everything. Manage invoice delivery and reminders in OpsMerge, not FreeAgent.

Direct Debit auto-collection (GoCardless)

If you collect by Direct Debit through FreeAgent's GoCardless integration, OpsMerge can flag each pushed invoice so FreeAgent collects it automatically — no manual "take payment" step at month-end.

How it works, in two stages:

1. At push — when OpsMerge pushes an invoice for a client you've opted in whose FreeAgent contact has an active Direct Debit mandate, OpsMerge pre-authorises GoCardless collection on the invoice (you'll see a "Take Payment with GoCardless" option appear on it in FreeAgent).
2. On the due date — OpsMerge then triggers the collection itself. FreeAgent does not auto-collect API-pushed invoices, so OpsMerge runs a daily job at 4pm that, once an invoice's due date has arrived, tells FreeAgent to take the Direct Debit. The actual debit and settlement are handled by FreeAgent/GoCardless from there.

So you don't press "Take Payment" yourself, and you don't need to configure collection timing in FreeAgent — OpsMerge collects on the due date, which you control via the invoice's payment terms (NET days).

Want it collected sooner than 4pm? Either wait for the 4pm trigger, or trigger it yourself in the FreeAgent portal — open the invoice and use its "Take payment with GoCardless" button to start the Direct Debit immediately.

The mandate must already exist in FreeAgent — OpsMerge never creates one. Set your customer up with a Direct Debit mandate in FreeAgent (or have FreeAgent email them a request) before expecting auto-collection. The first collection from a new mandate can take up to ~10 working days to clear.

Per-client opt-in

Auto-collection is off by default and enabled per client, so you choose exactly who gets collected automatically. A client's current mandate state (active / pending / inactive / failed) is shown read-only against the client, refreshed each time an invoice pushes.

When a client isn't opted in, or has no active mandate, the invoice still pushes normally — it simply isn't pre-authorised for Direct Debit, and you collect it however you would otherwise. Auto-collection is always best-effort and never blocks the invoice push.

Direct Debit clients aren't chased

Clients with auto-collection on and an active mandate are skipped by the overdue reminder and final notice emails by default — their payment is being collected automatically, so chasing them would only cause confusion. This is the Don't chase clients on active Direct Debit setting under Payment chasing; turn it off there if you want DD clients chased anyway.

Cards

Card payment links are self-serve only: FreeAgent can show a "pay online" link on an invoice, but there is no automatic card pull. Only GoCardless Direct Debit is collected automatically.

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.

Optionally, OpsMerge can email the client a payment confirmation when a synced payment fully pays their invoice — useful with Direct Debit so the client hears "we've collected it" instead of being chased. It's off by default; enable Email clients when an invoice is paid under Payment chasing. The wording is editable under Email Templates.

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.

A pushed invoice wasn't auto-collected by Direct Debit. Check, in order: the client is opted in to auto-collection; the client's contact has an active mandate in FreeAgent (mandate state is shown read-only against the client); GoCardless Direct Debit is enabled in your FreeAgent default payment options; and the mandate is GBP. If it's the customer's first-ever collection, allow up to ~10 working days. OpsMerge only pre-authorises collection — the timing and the debit itself are handled by FreeAgent/GoCardless.

Next

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