FreeAgent WooCommerce PRO

Feature overview (video)

Introduction

Invoicing Integration for FreeAgent and WooCommerce connects your WooCommerce store to FreeAgent (UK cloud accounting) via the official OAuth API. The integration ships in two parts:

Free plugin — available on WordPress.org. Covers manual invoicing, VAT number capture at checkout, contact management, PDF downloads and sensible UK-centric defaults.
PRO plugin — sold and licensed separately. Adds automation, credit notes, bulk tools, nightly grouped invoicing, richer emails, EC VAT MOSS flags, invoice payment links and more.

Free plugin — what you get

OAuth connection to FreeAgent via a developer application on dev.freeagent.com.
Manual invoice creation from each WooCommerce order screen.
Automatic find-or-update of FreeAgent contacts from billing data (matched by email).
VAT number field at checkout — works on both classic shortcode checkout and WooCommerce Block checkout. The optional “I want a VAT invoice” checkbox reveal is classic checkout only.
Line-level VAT rates read from WooCommerce tax configuration to avoid double-counting.
Optional VAT exemption basis text appended to invoice comments when any line is zero-rated.
Automatic EC status classification: UK/Non-EC, or Reverse Charge for EU VAT-registered billing countries.
Optional mark invoice as sent (sets status to Open in FreeAgent) when created.
Default bank account on invoices for remittance display in FreeAgent.
Default payment terms in days.
Default invoice comments with merge tags ({order_id}, {order_number}, {order_date}, {customer_name}, {customer_email}, {payment_method}).
Total mismatch warning when FreeAgent invoice total and WooCommerce order total differ after rounding.
PDF download from the order screen and from My Account → Invoices.
FreeAgent line item type per product / variation (Hours, Days, Weeks, Months, Years, Products, Services, Training, Expenses).
Optional debug logging via WooCommerce logs (OAuth secrets redacted).
Compatible with HPOS (High-Performance Order Storage).

PRO plugin — what it adds

Automatic invoice creation when orders reach configured statuses, or queuing for the nightly batch when grouped mode is on.
Automatic credit notes when an order reaches the WooCommerce Refunded status (per-order mode), or as part of the nightly consolidated batch (grouped mode).
Daily grouped (rollup) mode — batch many orders and refunds into one consolidated FreeAgent sales invoice and matching credit clusters per day, VAT-grouped and multi-currency aware, posted to a single nominated FreeAgent contact.
Automatic payment recording — books a bank receipt in FreeAgent when WooCommerce marks the order as paid.
Custom invoice reference using placeholders ({order_id}, {order_number}).
Income accounting category for invoice line items and a store-wide default item type (Products, Services, Training, Expenses).
Online invoice payment links — adds payment method flags to FreeAgent invoices (PayPal, GoCardless Direct Debit, GoCardless Instant Bank Pay, Stripe, Tyl by NatWest). Each provider must be enabled in your FreeAgent account.
EC VAT MOSS — store-wide default plus per-product / per-variation flags for qualifying EU digital supplies.
Invoice and credit note emails for per-order automation: send via FreeAgent template or attach PDF to WooCommerce order emails. Nightly consolidated documents are not emailed to individual customers.
Bulk actions on the orders list: create invoices, send via FreeAgent or WooCommerce, ZIP download of PDFs.
Licensed plugin updates via Devikit’s update channel when a valid PRO license is active.

Important: The PRO add-on requires the free plugin to be installed and active. They are separate plugin files managed independently.

1. Creating a FreeAgent OAuth application

FreeAgent uses OAuth — you must create a developer application on the FreeAgent portal before connecting the plugin. Each website needs its own application (creating one is free).

Go to https://dev.freeagent.com/ and sign in (or create a free developer account).
Click My Apps in the top navigation, then Create New App.
Enter a name (e.g. My Shop – WooCommerce) and a short description — both required.
In the OAuth Redirect URIs field paste the Redirect URI shown in the plugin under WooCommerce → FreeAgent → FreeAgent Connection. You can keep existing URIs; just add yours on a new line.
Click Create App. On the next screen, copy the OAuth Identifier and OAuth Secret values.
Paste them into the plugin’s Connection tab, click Save Credentials, then Connect to FreeAgent and approve access in the browser.

Keep the OAuth Secret private — do not commit it to a public repository. Tokens are stored in the WordPress database. The optional debug log redacts sensitive values.

2. Installation

Free plugin

Go to Plugins → Add New and search for Invoicing Integration for FreeAgent and WooCommerce, or upload the ZIP directly.
Click Install, then Activate.
Ensure WooCommerce is active (the plugin requires it).

PRO plugin

Install and activate the free plugin first.
Upload the PRO ZIP via Plugins → Add New → Upload Plugin and activate it.
Go to WooCommerce → FreeAgent → License tab and enter your license key. PRO features activate only when the license is valid.

3. FreeAgent Connection tab

Path: WooCommerce → FreeAgent → FreeAgent Connection.

Documentation link — opens the full written guide.
OAuth Redirect URI — read-only field showing the URL you must add to your FreeAgent developer application. Copy it before creating your app.
OAuth Identifier / OAuth Secret — paste values from your FreeAgent developer app, then click Save Credentials.
Connect to FreeAgent — appears after credentials are saved. Starts the OAuth browser flow.
Test Connection — once connected, checks the stored token is still valid with a quick API call.
Disconnect FreeAgent — revokes and removes the stored token.

After a successful connection the plugin fetches and caches your company subdomain so order and invoice links in admin point to your own FreeAgent URL (e.g. yourcompany.freeagent.com/invoices/…).

4. Recommended WooCommerce settings

Invoice totals come from WooCommerce line items and tax configuration. For predictable results:

Configure standard / reduced / zero VAT rates in WooCommerce → Settings → Tax to match how you price and trade.
Use 2 decimal places — rounding differences between Woo and FreeAgent trigger the mismatch warning.
If you are not VAT-registered, disable Enable tax rates and calculations in WooCommerce and all lines will be zero-rated.

5. Store tab

Path: WooCommerce → FreeAgent → Store.

Controls the VAT number field shown at checkout.

Hide — the field is never shown. Works on classic and Block checkout.
Always visible — the field is always shown. Works on classic and Block checkout.
Show “I want a VAT invoice” checkbox — the VAT field is hidden until the customer ticks the checkbox. Works on classic checkout only. On Block checkout the field follows the Hide / Always visible rule instead.
Checkbox label — customise the wording next to the checkbox (default: “I want a VAT invoice”).
VAT field required — when checked, checkout cannot be submitted without a VAT number (when the field is visible).

6. Invoicing tab

Path: WooCommerce → FreeAgent → Invoicing.

Accounting defaults applied when invoices are created.

Available on the free plugin

Bank account — FreeAgent bank account shown on invoice remittance advice. Use Reload bank accounts if you add accounts in FreeAgent.
Payment terms (days) — how many days before the invoice is overdue. Enter 0 for due on receipt.
Mark as sent — when ticked, new invoices are created with status Open (sent) rather than Draft.
Invoice comments / notes — default text added to every invoice. Supports merge tags: {order_id}, {order_number}, {order_date}, {customer_name}, {customer_email}, {payment_method}.
VAT exemption basis — statutory reference (e.g. VATA 1994 s.30) appended to invoice comments when zero-rated lines appear, so you don’t retype it every time.

Without PRO, the rows below appear as disabled previews so you can see what unlocks with the add-on.

PRO-only fields on the same tab

Accounting category — FreeAgent income nominal applied to all invoice line items. Use Reload to refresh the list from FreeAgent.
Default item type — FreeAgent item type used when a product has no override (Products, Services, Training, Expenses).
Online invoice payment links — enables FreeAgent-hosted pay buttons on PDF invoices. Options: PayPal, GoCardless Direct Debit mandate, GoCardless Instant Bank Pay, Stripe, Tyl by NatWest. Each provider must also be enabled inside your FreeAgent account. This sends API flags only — WooCommerce order status is not changed.
Record payment automatically — creates a FreeAgent bank transaction linked to the invoice (equivalent to recording payment manually). Fires in two cases: (1) an invoice is created for an order that is already paid, or (2) the order moves to Processing or Completed and an invoice already exists. Requires a bank account to be selected above.
Custom invoice reference — optional pattern added to FreeAgent invoices. Leave blank to use FreeAgent’s own sequential numbering. Supported variables: {order_id}, {order_number}.
EC VAT MOSS (store default) — treats catalogue products as EC VAT MOSS supplies by default. Applies when WooCommerce billing is in an EU Member State, no VAT number is captured, and every paid product line qualifies as a MOSS supply (via this toggle or per-product flags). Orders containing only fees or shipping are not affected.

7. Product and variation settings

FreeAgent line item type (free plugin)

On each simple product, WooCommerce subscription product, or variation you can select a FreeAgent item type: Hours, Days, Weeks, Months, Years, Products, Services, Training, Expenses. When building the invoice, the plugin checks the variation first, then the parent product, then the PRO store default (if PRO is active), and finally falls back to Products.

EC VAT MOSS flag (PRO)

With PRO active, each product and variation can be marked as a MOSS-eligible supply. This works together with the store-wide EC VAT MOSS default on the Invoicing tab so qualifying EU digital-goods orders are classified as EC VAT MOSS on the FreeAgent invoice when all conditions match.

8. Order screen — FreeAgent panel

Every WooCommerce order has a FreeAgent sidebar panel.

Before an invoice exists

Create Invoice button — calls the FreeAgent API to create the invoice immediately using the defaults from the Invoicing tab.
If the API returns an error, the error message is displayed with a Retry button.
A spinner shows while the request is in progress.

After an invoice is created

The FreeAgent invoice reference or number is displayed.
View in FreeAgent — opens the invoice in FreeAgent directly.
Download PDF — fetches the PDF from FreeAgent on demand.
Total mismatch banner — if the FreeAgent invoice total and WooCommerce order total differ after rounding, an orange warning is shown with both values and the difference. Any automated PRO customer email is withheld.
Send Invoice via FreeAgent and Send Invoice via WooCommerce — appear as locked buttons in the free plugin; available with PRO.

PRO additions

Active Send Invoice via FreeAgent / Send Invoice via WooCommerce buttons to manually email the invoice to the customer.
Credit Note section — create a FreeAgent credit note once refunds exist in WooCommerce, then send it via FreeAgent or WooCommerce.

9. Orders list

The WooCommerce orders table shows a FreeAgent column with invoice identifiers, PDF links.

10. Customer — My Account

Logged-in customers see an Invoices section in My Account where they can download PDF invoices for their own orders. With PRO, credit note PDFs are also available there.

11. Automation tab (PRO)

Path: WooCommerce → FreeAgent → Automation.

Daily grouped (rollup) mode — optional

Turn this on to replace per-order automatic invoicing with a single consolidated FreeAgent invoice per day. All matching orders are queued locally and posted to the FreeAgent contact you choose. Refunds queue as clustered credit notes in the same nightly run. Consolidated documents are internal bookkeeping summaries — the plugin never emails them to individual customers.

Grouped sales & credits — enable the queue; choose the Grouped documents contact in FreeAgent (usually a shop-wide or cash-sales contact). Use Reload contacts if the list is stale.
Saving with only this box ticked but no contact selected will not activate grouping. A valid contact must be saved at the same time.
While grouped mode is on, per-order invoice automation and per-order credit note automation below are disabled. Only the sales order status checkboxes remain active (they control which orders enter the nightly queue).
Manual invoice and credit note buttons on individual orders remain available regardless of mode.

Automatic invoice (per-order, grouped mode off)

Enable automation — creates a FreeAgent invoice whenever an order moves into a checked status.
Order status — tick the statuses that should trigger invoicing (Pending payment, Processing, On hold, Completed, or any custom status). Cancelled, Refunded and Failed are excluded.
Record payment — after invoicing, if the order is already paid (or becomes paid), books a FreeAgent bank transaction for the invoice.
Send invoice email — via FreeAgent template and/or as a WooCommerce order email with PDF attached. Both options apply to per-order automation only.

Automatic credit note (per-order, grouped mode off)

Enable automation — creates a FreeAgent credit note when the WooCommerce order reaches Refunded status. This is the only trigger; there is no status multi-select. Partial refunds that do not move the order to Refunded do not trigger this automatically.
Send email — via FreeAgent template and/or as a WooCommerce email with credit note PDF attached.

12. Bulk actions (PRO)

The WooCommerce orders list gains additional bulk actions when PRO is active:

Create invoices — issue FreeAgent invoices for selected orders in one go.
ZIP invoice PDFs — download a ZIP of PDF invoices for selected orders.
Send invoices via FreeAgent / via WooCommerce — email invoices to customers in bulk.

13. VAT, EC status and MOSS

The free plugin automatically classifies invoices as UK/Non-EC or Reverse Charge based on the billing country and whether a VAT number was provided at checkout.
PRO adds a store-wide EC VAT MOSS default plus per-product MOSS eligibility flags for qualifying EU digital goods or services (see the Invoicing tab and product settings).
EC status rules are a best-effort default based on WooCommerce data. Always verify classification with your accountant — FreeAgent and HMRC/EU VAT obligations are your responsibility.

14. Advanced tab

Path: WooCommerce → FreeAgent → Advanced.

Enable debug logging — logs all FreeAgent API requests and responses to WooCommerce logs (source: devikit_freeagent_debug). View them at WooCommerce → Status → Logs. Sensitive OAuth values are always redacted. Disable this in production once troubleshooting is done.

15. License (PRO)

PRO features are gated behind a valid license key purchased from Devikit.

Enter your license key after activating the PRO plugin.
An active license enables automatic update packages from Devikit’s signed download endpoint.
To move the license to a different site, deactivate it here first.

16. Updates

Free plugin — updates appear in Plugins like any WordPress.org plugin.
PRO plugin — updates appear in Plugins when a valid license is active and Devikit’s server reports a newer version than the one installed.

17. Support

PRO customers: contact via email hi@devikit.co.uk or contact form.

Free users: use the WordPress.org support forum.

18. Troubleshooting

Invoice total differs from order total by a penny (or a few pence)

This is a known rounding limitation that arises from how WooCommerce and FreeAgent each handle decimal arithmetic — not a bug in the plugin.

Why it happens: WooCommerce can store prices and tax with more than two decimal places internally. When the plugin sends line items to FreeAgent, FreeAgent rounds each line to two decimal places before summing. Because the rounding point is different (WooCommerce sums first, FreeAgent rounds per-line first), the final totals can diverge by one or two pence even when every individual number looks correct.

What the plugin does: When it detects a mismatch between the WooCommerce order total and the FreeAgent invoice total, it shows an orange warning banner on the order screen. Automated PRO customer emails are withheld until the totals match, so a mismatched invoice is never emailed to a customer automatically.

How to minimise the risk:

In WooCommerce → Settings → Tax, try disabling Round tax at subtotal level.
Set WooCommerce to 2 decimal places (WooCommerce → Settings → General). More decimal places increase the chance of rounding drift.

What the plugin cannot do: The integration reads numbers from WooCommerce and passes them to the FreeAgent API as-is. It cannot override how either system rounds internally. If a rounding mismatch persists after adjusting WooCommerce rounding settings, please consult your accountant on how to handle it within FreeAgent — the correct approach depends on your accounting method.