FreeAgent integration | SparkReceipt Help

SparkReceipt connects directly to FreeAgent, the UK accounting platform. Connect from Integrations in the SparkReceipt web app, and your FreeAgent categories, bank accounts, VAT rates and contacts are imported so you can publish Expenses to FreeAgent as Bills and Income documents as Invoices, with the original file attached and the payment recorded. SparkReceipt currently connects to UK FreeAgent companies only.

What the FreeAgent integration does

The FreeAgent integration links a SparkReceipt account to a single FreeAgent company so that your accounting reference data stays in sync and the documents you capture in SparkReceipt can be posted straight into FreeAgent.

Once connected, SparkReceipt pulls reference data from FreeAgent and pushes processed documents to FreeAgent:

From FreeAgent → SparkReceipt (read-only sync):
- Categories – FreeAgent's admin expenses and cost of sales categories become expense categories in SparkReceipt, and FreeAgent's income categories become income categories. Sub-accounts (for example nominal code 602-1) are nested under their parent category. Balance-sheet categories are not imported.
- Income accounts – your FreeAgent income categories are also listed as income accounts, which is what an Income document's lines are booked to. Sales is picked as the default.
- Bank accounts – your active FreeAgent bank accounts and credit card accounts are imported as purchase accounts, so a paid Expense can be recorded against the right account in FreeAgent. Personal accounts and inactive accounts are skipped.
- VAT rates – if your FreeAgent company is VAT registered, SparkReceipt creates one tax code per VAT rate the company reports (for example VAT 20%), plus Exempt and Out of scope. A company that is not VAT registered gets no tax codes, and tax tracking is switched off for it (see How VAT is handled).
- Contacts – FreeAgent suppliers are imported as merchants (for Expenses) and FreeAgent clients as customers (for Income documents).
- Company details – company name, company type, home currency and country are read from FreeAgent and shown on the connection settings page.
From SparkReceipt → FreeAgent (publishing documents):
- Expense documents (receipts, supplier invoices) are published to FreeAgent as Bills. A refund is published as a Bill with negative amounts, which FreeAgent shows as Refunded.
- Income documents (sales invoices, sales receipts) are published to FreeAgent as Invoices and marked as sent. FreeAgent assigns the invoice number.
- A paid document also gets a bank transaction explanation on the bank account you selected, which is how a Bill or Invoice becomes Paid in FreeAgent. The explanation creates a manual bank transaction on that account in FreeAgent.
- The original file is attached to the Bill. FreeAgent invoices cannot carry an attachment, so files on an Income document travel with the payment explanation instead – see Attachments.

SparkReceipt does not create categories in FreeAgent. Every document you publish must use a category that came from FreeAgent.

Prerequisites

A UK FreeAgent company. SparkReceipt checks the company type when you connect – a FreeAgent company set up as a US or universal (non-UK) business is refused with the message SparkReceipt currently connects to UK FreeAgent companies only.
The FreeAgent user who connects needs at least Banking access in that FreeAgent company (FreeAgent permission level 6 or higher; company owners have full access). SparkReceipt needs that level to record payments. A user with a lower level is refused with a message asking the FreeAgent company owner to raise their access, or to connect as the owner.
Only one accounting integration can be active on a SparkReceipt account at a time. If you already have QuickBooks Online, Xero, FreshBooks or Zoho Books connected, remove that connection before connecting FreeAgent.
The person doing the connecting must be a SparkReceipt administrator or accountant on the account – those are the roles that can see the Integrations settings.

Connecting and initial setup

The setup flow is:

Log in to SparkReceipt as an administrator or accountant and open the Integrations entry in the left-hand sidebar.
Under the Accounting section, click Connect to FreeAgent. You'll be redirected to FreeAgent to sign in and approve SparkReceipt's access.
There is no company picker: a FreeAgent login belongs to exactly one FreeAgent company, and that is the company SparkReceipt connects to. To connect a different company, sign in to FreeAgent with a user of that company.
Back in SparkReceipt you'll see Verifying your FreeAgent connection. Please hold tight. while SparkReceipt checks that the company is a UK company and that your FreeAgent user has Banking access, then runs the initial sync – categories, income accounts, bank accounts, VAT rates and contacts, plus your company details. If either check fails you'll see an error dialog with the reason; fix it in FreeAgent and connect again.
When the sync completes, you land on the FreeAgent Connection Settings page in SparkReceipt. The Imported from FreeAgent section lets you review the imported data; the Preferences section holds the publishing settings.
Right after connecting, SparkReceipt asks whether it should auto-publish new expenses to FreeAgent. If you turn it on, every new Expense is published as soon as it is scanned. You can change this later under Preferences on the same settings page (Auto-publish new expenses).

If you cancel on FreeAgent's side, SparkReceipt shows Connection cancelled and nothing is connected – you can try again whenever you're ready.

From that point on, documents you process in SparkReceipt can be published to FreeAgent from the document view.

Keeping the imported data current

Changes you make in FreeAgent – a new category, a new bank account, a new contact – appear in SparkReceipt after the next sync. To pull them in right away, open the FreeAgent Connection Settings page and click Sync now.

Publishing documents to FreeAgent

Unless you turned on auto-publish, publishing to FreeAgent is a manual step in SparkReceipt. Documents only move to FreeAgent when you publish them.

Publish a single document

Open the document in SparkReceipt and click Publish to FreeAgent in the document view. The publish editor shows what will be sent and lets you set the FreeAgent-specific details described below. After publishing, the editor shows the FreeAgent record (for example Bill #345192) with a Show in FreeAgent link that opens the Bill or Invoice in your FreeAgent company.

Publish several documents at once

In the documents list, select the documents you want to publish and click Publish in the bulk-action bar at the top of the list (in the browse view the same action is labelled Publish to accounting). The dialog lists which documents can be published, and offers Rewrite already published documents in case you've made edits in SparkReceipt that you want reflected in FreeAgent.

Publishing an Expense as a Bill

Every Expense is published as a FreeAgent Bill, whether it is a till receipt or a supplier invoice. The publish editor asks for:

Merchant – the Bill's contact in FreeAgent. A merchant is required: without one the Bill cannot be created. If the merchant's name matches an existing FreeAgent contact it is reused; otherwise SparkReceipt creates the contact in FreeAgent. A merchant and a payer with the same name share one FreeAgent contact, which is how FreeAgent models a business that is both a supplier and a client.
Category – each line item's category must be one imported from FreeAgent. SparkReceipt publishes one Bill line per line item, each booked to its own FreeAgent category. FreeAgent accepts at most 40 lines on a Bill; a longer document has its extra lines combined by category and VAT rate, and if it still does not fit, the publish is refused with a message asking you to merge some lines.
Line tax codes – when tax tracking is on, every line that carries VAT must be matched to a FreeAgent VAT rate. See How VAT is handled.
Account – the FreeAgent bank or credit card account the Expense was paid from. This is where SparkReceipt records the payment.
Publish as – a read-only value that always shows Bill for FreeAgent.

The Bill's reference is the document's reference number if it has one, otherwise the start of the document description, otherwise the document's SparkReceipt number (for example SR-42). The Bill's due date is the document's due date, or the document date when there is no due date.

Marking the Bill paid. A receipt is treated as paid by definition; a supplier invoice is treated as paid when its paid status is set in SparkReceipt. For a paid Expense, SparkReceipt records a bank transaction explanation on the selected Account (or, when the document has no account, on the Default purchase account set in Preferences). FreeAgent then shows the Bill as Paid and adds a manual bank transaction to that account. When the same payment later arrives through your bank feed with the same date and amount, FreeAgent matches the imported line to the manual transaction rather than creating a duplicate.

The payment is skipped – and the Bill is left unpaid in FreeAgent – in two cases, each reported as a warning on the document:

No bank account is selected for the document and no default purchase account is set.
The document is in a different currency from the selected bank account (for example a EUR receipt against a GBP account). Explanations are always in the bank account's currency, so foreign-currency documents are published unpaid; record the payment in FreeAgent yourself.

Refunds. A refund (an Expense with a negative total) is published as a Bill with negative line amounts. FreeAgent shows it as Refunded once its payment explanation is recorded. The Publish as value stays Bill.

Publishing an Income document as an Invoice

Every Income document is published as a FreeAgent Invoice and immediately marked as sent, so it counts in your FreeAgent ledger. FreeAgent assigns the invoice number. The publish editor asks for:

Payer – the Invoice's contact in FreeAgent, matched or created in the same way as a merchant.
Income Account – the FreeAgent income category every line of the Invoice is booked to. It defaults to the Default income account set in Preferences (Sales after the first sync). A line-item category is not required on Income documents for FreeAgent.
Line tax codes – if your company is VAT registered, every line must be matched to a FreeAgent VAT rate, regardless of the tax handling preference. Out of scope is not offered on Income documents; use Exempt.
Publish as – always Invoice.

If the Income document is marked as paid in SparkReceipt, a bank transaction explanation is recorded on the document's payment account (or the default purchase account) under the same currency rule as for Bills, and the Invoice shows as Paid in FreeAgent.

Documents added before connecting FreeAgent

Any documents that were processed in SparkReceipt before you connected FreeAgent were categorized using SparkReceipt's generic categories. Those generic categories aren't mapped to a FreeAgent category, so publishing them shows the error Category is not available in FreeAgent until they're moved to a FreeAgent-synced category. Two ways to fix this:

Pick a FreeAgent-synced category manually. Open the document, change the category to one of the FreeAgent expense categories, and publish.
Rescan the document. Use the Rescan document action on the document. The AI re-categorizes the document against the categories that are now available, which includes your FreeAgent categories.

If the category you need doesn't exist in FreeAgent at all, create it in FreeAgent first and then click Sync now on the FreeAgent Connection Settings page so it shows up in SparkReceipt.

How VAT is handled

FreeAgent has no tax-code list of its own – each Bill or Invoice line carries a VAT percentage and a status (taxable, exempt or out of scope). SparkReceipt builds its FreeAgent tax codes from the VAT rates your company reports, so what you see depends on whether the company is VAT registered:

VAT-registered company. The Tax handling when publishing preference defaults to Track tax. Each Expense line is sent net, with its matched FreeAgent VAT rate, and FreeAgent adds the VAT. For a Bill in your home currency SparkReceipt also sends the exact VAT amount from the receipt, so the Bill total in FreeAgent equals the receipt total rather than a rate-derived approximation. A line that carries VAT but has no FreeAgent VAT rate matched is refused with The line "…" has VAT but no FreeAgent VAT rate – pick a rate for it in Line tax codes and publish again. A line with no VAT is sent at 0% so FreeAgent never applies a category's default rate on top of what the receipt shows.
Company not VAT registered. FreeAgent does not accept explicit VAT rates on such a company, so SparkReceipt imports no tax codes and sets Tax handling when publishing to Do not track tax. Expenses are published as gross totals with no VAT breakdown.

Switching a VAT-registered company to Do not track tax changes Expenses only – they publish as gross totals with no VAT. Income Invoices keep their VAT rates either way, because an Invoice line in FreeAgent is a net price and FreeAgent would otherwise add output VAT on top of your gross amount.

Attachments

FreeAgent accepts PDF, JPEG, PNG and GIF files, and only one file on a Bill; Invoices have no attachment slot at all. SparkReceipt works within those limits as follows:

Photos in other formats (WebP, HEIC/HEIF, AVIF, SVG, TIFF, BMP) are converted to JPG before upload. Other file types, such as Word or Excel documents, are not attached – the document is still published, with a warning naming the file.
FreeAgent limits each file to 5 MB. An image over the limit is compressed, then scaled down, until it fits. A PDF over 5 MB is not attached, with a warning.
On a Bill, the document's first file is attached to the Bill itself. Any further files are attached to the payment explanation when the Expense is paid; on an unpaid Bill they are not attached, with a warning.
On an Invoice, all files are attached to the payment explanation when the Income document is paid. On an unpaid Invoice no file is attached, with a warning.

Warnings appear on the document's FreeAgent publishing section after the publish completes; the record itself is still created.

Updating a published document

If you edit a document after publishing it, open it and click Update in FreeAgent (or use Rewrite already published documents when bulk publishing). SparkReceipt rewrites the FreeAgent record with the current document:

A paid Bill is locked in FreeAgent while its payment explanation exists. SparkReceipt removes its own explanation, updates the Bill, then records the explanation again, so one explanation remains.
A sent Invoice is locked too. SparkReceipt puts it back to draft, updates it, and marks it as sent again (removing and re-recording the payment explanation first when the Invoice was paid).
If the record no longer exists in FreeAgent, SparkReceipt creates a new one.
If a document's type changes between Expense and Income after publishing, the old FreeAgent record is removed and the document is published as the new type.

Bills you have reconciled by hand in FreeAgent. SparkReceipt finds the explanation to remove by the date the Bill was paid on the account it published to. If you explained the Bill yourself from an imported bank transaction rather than through SparkReceipt, an update from SparkReceipt can either fail with FreeAgent's locked message or replace your explanation with a manual transaction of its own. For a Bill you've already reconciled in FreeAgent, make further edits in FreeAgent rather than republishing from SparkReceipt.

Removing a document from FreeAgent

In the publish editor, click Remove from FreeAgent. SparkReceipt deletes the payment explanation it recorded (which also removes the manual bank transaction), then deletes the Bill or Invoice – a sent Invoice is put back to draft first, because FreeAgent only deletes draft invoices. The document in SparkReceipt goes back to Not published and can be published again later.

Limitations

UK companies only. US and universal (non-UK) FreeAgent companies cannot be connected.
One accounting integration per account. Remove QuickBooks Online, Xero, FreshBooks or Zoho Books before connecting FreeAgent.
One FreeAgent company per connection. To connect a different company, connect with a FreeAgent user of that company.
No category creation in FreeAgent. Categories flow from FreeAgent to SparkReceipt only.
Attachments: one file per Bill, none on Invoices, 5 MB per file, PDF/JPEG/PNG/GIF only (other images are converted). See Attachments.
40 lines per Bill. Extra lines are combined by category and VAT rate where possible.
Foreign-currency payments are not recorded. Documents in a currency other than the selected bank account's are published unpaid. To publish everything in your home currency instead, set Multi-currency behavior to Always convert to home currency under Preferences.
Locked records. Paid Bills and sent Invoices are updated and removed by SparkReceipt only through the explanation-first and draft-first steps described above; a Bill explained by hand in FreeAgent may refuse an update.

Troubleshooting and common errors

When a publish fails, SparkReceipt writes the reason onto the document itself – open the document in the web app and read the message in its FreeAgent publishing section before changing anything.

SparkReceipt currently connects to UK FreeAgent companies only – the FreeAgent company you signed in to is set up as a non-UK business. Only UK company types can be connected.
Your FreeAgent user needs Banking access (permission level 6 or higher) – ask the FreeAgent company owner to raise your user's permission level in FreeAgent, or connect as the owner.
Category is not available in FreeAgent / The category "…" isn't linked to a FreeAgent category – the document uses a SparkReceipt category that did not come from FreeAgent. Pick a FreeAgent category or rescan the document.
The line "…" has VAT but no FreeAgent VAT rate – match the line to a VAT rate under Line tax codes.
No FreeAgent income category is selected for this document – set the Income Account in the publish editor, or a Default income account in Preferences.
The document was published, but no payment was recorded… – a warning, not a failure. Either no bank account was selected (choose one under Account, or set a Default purchase account) or the document's currency differs from the account's.
The file "…" wasn't attached… – a warning; the record exists in FreeAgent without that file. See Attachments.
Your FreeAgent connection has expired – click Reauthorize on the FreeAgent Connection Settings page and sign in to FreeAgent again, then publish again.
FreeAgent is limiting requests right now – FreeAgent's rate limit was hit. Wait a few minutes and publish again.
A message quoting FreeAgent, for example "…is locked and cannot be changed" – FreeAgent refused the change. This usually means the Bill or Invoice was explained or edited by hand in FreeAgent since SparkReceipt published it; make the edit in FreeAgent, or unexplain the record there and update again.

If something doesn't look right – a missing category, a document that failed to publish, an unexpected error – let us know through the in-app chat widget. That's the fastest way to get help.

Disconnecting FreeAgent

Open the FreeAgent Connection Settings page and click Remove connection, then confirm. SparkReceipt removes the connection, turns off auto-publish, and clears the published state from your documents – they read Not published again, although the Bills and Invoices already created stay in FreeAgent. Imported categories and contacts stay in SparkReceipt but are no longer linked to FreeAgent (categories hidden by the sync become visible again); the imported bank accounts are removed.

FreeAgent does not let connected apps revoke their own access, so SparkReceipt stays listed as an approved app in your FreeAgent settings until you remove it there.

FreeAgent is a trademark of FreeAgent Central Limited. SparkReceipt is an independent, third-party integration and is not affiliated with, endorsed by or sponsored by FreeAgent.