Connecting Mucka to FreeAgent means your clients, invoices and customer payments flow straight into FreeAgent. FreeAgent's the popular pick with UK sole traders and small trades shops — Mucka stays the place you raise an invoice; FreeAgent is where your bookkeeper and accountant see it land seconds later.
Live end-to-end. Contacts, invoices, payments, and "ask Mucka what's outstanding" tools all work. If a customer pays direct in FreeAgent, Mucka ticks the invoice over to paid automatically (via a 5-minute background poll — FreeAgent has no webhooks, so it's not instant like Xero + QuickBooks, but it's close).
Before invoices start syncing you need to pick a default sales category and bank account using the Map accounts button on the FreeAgent panel. Contacts sync the moment you connect; invoices and payments flow as soon as mapping is saved.
Connect your FreeAgent company
Head to Settings → Integrations → FreeAgent and tap Connect FreeAgent.
FreeAgent asks you to sign in and approve the permissions Mucka needs — full access to your FreeAgent company so it can read + write contacts, invoices, payments and reports. Approve and FreeAgent bounces you back to Mucka with a "Connected" confirmation.
Already have clients in FreeAgent? Bring them in
Coming to Mucka with an established FreeAgent company? Tap Import from FreeAgent on the panel to pull your existing contacts (and, if you want, their invoice history) into Mucka — matched against your Mucka clients first so nothing is duplicated. Full walkthrough: Import your existing clients.
One FreeAgent company per Mucka workspace
If you run multiple businesses through separate FreeAgent companies, you need a separate Mucka workspace for each. Mucka pins each workspace to one FreeAgent company so the right contacts and invoices land in the right place.
What flows across automatically
Contacts. Every client you create in Mucka — through the app, voice, WhatsApp or the CSV importer — is pushed into FreeAgent Contacts in a few seconds. Mapped fields:
- organisation_name (commercial clients) or first_name / last_name (residential)
- email (client email, falling back to company email)
- phone_number
- address1 / postcode / country (FreeAgent uses flat address fields, not nested — bit unusual)
- sales_tax_registration_number if the client has a VAT number in Mucka
- notes carries
mucka:<client_id>so an operator can trace FreeAgent records back to Mucka
Update a client in Mucka and the changes flow through.
Invoices. When you raise an invoice in Mucka, it lands in FreeAgent with line items, reference number, due date and VAT all carried across. FreeAgent auto-numbers the invoice from your company sequence unless you set an explicit reference on the Mucka side.
FreeAgent uses "transitions" not status edits, so Mucka creates every invoice as Draft first and then fires mark_as_sent to move it to Open — same end result as Xero + QuickBooks, just two API calls instead of one.
Customer payments. Recording a payment against an invoice in Mucka pushes a matching bank_transaction_explanation into FreeAgent linked to the same invoice on the bank account you picked in mapping. FreeAgent auto-flips the invoice status to Paid when the explanation clears the outstanding balance.
If your customer pays direct through FreeAgent (bank feed, Stripe etc.), Mucka's 5-minute background poll notices the paid transition and ticks the Mucka invoice over to Paid too — no double entry.
Voids. Voiding a Mucka invoice fires mark_as_cancelled on the FreeAgent side. Nicer than QuickBooks + Xero — FreeAgent lets you cancel a sent-and-paid invoice; the payment stays attached as a refund task for the bookkeeper. No credit-note dance to jump through.
Map accounts — pick your defaults
Tap Map accounts on the FreeAgent panel and choose:
- Default sales category — the nominal code invoice income lands under (e.g. "001 — Sales" for most trades workspaces; you can split out "Boiler Service", "Installations" etc. if your chart of accounts has them)
- Default bank account — where customer payments deposit. Primary bank floats to the top of the list. Credit-card accounts are hidden (customer receipts never land there); PayPal / Stripe balances qualify because they're FreeAgent's "Ecommerce" account type
- VAT treatment — optional. Leave on FreeAgent's default (Non-EC) for a normal UK invoice. Switch to Reverse Charge (CIS / construction) if you invoice VAT-registered contractors under CIS — every invoice then tags for the domestic reverse charge under SI 2019/892
Save the mapping and any invoices that were waiting (raised in Mucka after you connected but before mapping was complete) push to FreeAgent straight away in the background.
The sheet also has an Also push the last 90 days of invoices to FreeAgent on save tick. Leave it on if you've just connected FreeAgent and want your existing invoices in there too. Untick if you're mid-year and don't want a flood.
"Sync contacts now" + "Sync invoices now" — manual backfills
If you've got hundreds of clients in Mucka already, the first connect pushes them all across in the background. You can re-trigger the same sweep from the panel any time using Sync contacts now — useful if you've imported a big CSV and want to nudge FreeAgent to catch up.
Sync invoices now does the same for invoices created in the last 90 days that don't have a FreeAgent link yet — handy if FreeAgent was down or your mapping was incomplete when an invoice was raised. It only enables once mapping is set; until then the button is greyed out.
Mucka skips records that are already in FreeAgent, so you can tap either Sync button without worrying about duplicates. Both are rate-limited to one tap every 30 seconds per workspace.
Permission needed to connect
Only people with the manage billing permission can connect or disconnect FreeAgent. Engineers see the connection state on the panel ("FreeAgent is connected to Ryan's Plumbing Ltd") but can't change it. Same rule as the rest of the billing tab.
Disconnect
The Disconnect FreeAgent button removes Mucka's stored access on your workspace and stops any new contacts, invoices or payments from flowing across.
FreeAgent doesn't offer a public "revoke" endpoint (unlike Xero and QuickBooks), so if you also want Mucka removed from your FreeAgent Connected Apps list, revoke us from FreeAgent → Settings → Connected Apps. Records already pushed stay in FreeAgent as accounting history — FreeAgent won't let Mucka delete them, and you wouldn't want it to.
The disconnect sheet offers a default-on tick: Also clear the FreeAgent badges from Mucka clients and invoices. Leave it ticked unless you specifically want Mucka to keep showing the old "synced to FreeAgent" markers on entities whose FreeAgent link is no longer active.
Sandbox vs production
Your Mucka workspace points at the FreeAgent environment that matches whichever Mucka deployment you're using. Production Mucka talks to your real FreeAgent company. Dev / preview Mucka talks to FreeAgent sandbox companies (FreeAgent's free test orgs), so you can experiment with the integration without touching your real books. The panel shows a small Sandbox tag when you're on a sandbox connection.
Troubleshooting
"Connection expired" — FreeAgent sessions rarely expire (refresh tokens last ~20 years) but a password reset on the FreeAgent side revokes them. Tap Reconnect on the panel and approve again; Mucka catches up on anything missed during the gap.
"Access revoked" — happens when somebody on the FreeAgent side removes Mucka from Connected Apps. Same fix: tap Reconnect.
A client didn't sync — Mucka shows the last sync error on the FreeAgent panel. Tap Sync contacts now to retry. Free-trial FreeAgent accounts cap at 2 contacts — a common trip-hazard during setup; upgrade the FreeAgent account to a paid tier and Mucka will push the rest.
Automatic retry — Mucka catches up on its own
Mucka runs a quiet retry sweep every hour (at forty-past). If anything failed to push to FreeAgent in the previous hour — bad timing, FreeAgent hiccup, network blip — the sweep retries the last 24 hours of contacts and invoices for any connection still showing an error. Most of the time you'll never notice the failure happened.
There's also a 5-minute background poll that checks FreeAgent for newly-paid invoices — that's how "customer paid direct in FreeAgent" tick-overs land on the Mucka side. FreeAgent has no webhooks, so polling is how the reverse-sync works. It's a bit slower than the instant Xero + QuickBooks flows but rarely more than 5 minutes behind.
Ask Mucka about FreeAgent
Once FreeAgent is connected, you can ask Mucka about your accounting position in plain English. Mucka pulls the numbers live from FreeAgent and reads them back. Example asks:
- "What's outstanding in FreeAgent?" — lists open invoices, oldest first
- "Anything over 90 days overdue in FA?" — pulls aged receivables and reads the worst offenders (reconstructed on the Mucka side because FreeAgent has no aged-debt endpoint, but the buckets match Xero + QuickBooks)
- "Who owes me money on FreeAgent?" — same, ranked by amount
- "What was my month on FreeAgent?" / "How did Q1 look?" — pulls the Profit & Loss for the period
- "Push that invoice to FreeAgent" — when an invoice didn't sync automatically (rare) or you want a retry, Mucka stages a one-tap approval card
- "Draft that quote as a FreeAgent invoice" — accepted quote into a Mucka draft + FreeAgent Draft, ready for your bookkeeper to finalise
Same trust model as everywhere else in Mucka: query tools fire instantly; push tools always wait for a one-tap confirmation. Mucka never pushes data to FreeAgent without explicit owner approval.
Already on Xero or QuickBooks?
You can have FreeAgent connected alongside Xero AND/OR QuickBooks on the same Mucka workspace. Every Mucka client, invoice and payment then fans out to all connected providers, useful if you're mid-migration from one to another. The panel shows an amber heads-up when a second provider is also connected so you don't forget. Disconnect the ones you don't want going forward.
If Mucka's AI is unclear which provider you're asking about, it'll ask ("Xero, QuickBooks or FreeAgent?") rather than guess. If you name one directly it fires straight into that provider's tool.