FreeAgent Sync for WooCommerce

Overview

↑ Back to top

The FreeAgent Sync for WooCommerce extension synchronizes your WooCommerce orders with invoices in your FreeAgent account. There are two modes available for generating invoices:

• Summarized Mode (recommended): Invoices are created daily to record accumulated sales, organized by tax amount, currency, and sales type. This is the recommended mode, especially for larger stores.
• Detailed Mode: Invoices are generated automatically when a WooCommerce order is placed, creating a corresponding invoice along with a contact for that user. You can also synchronize payments between FreeAgent invoices and WooCommerce orders.

Installation

↑ Back to top

1. Download the extension from your dashboard
2. Go to Plugins > Add New > Upload and select the ZIP file you just downloaded
3. Click Install Now and Activate
4. Setup the extension how you prefer by visiting WooCommerce > Settings > Integration (see next section on configuration)

Setup and Configuration

↑ Back to top

In order to establish a connection to your FreeAgent account you must setup a FreeAgent Application which requires a development account.  You can create an account here and follow through the following steps to create your application:

• Click on the My Apps link on the top of the page.
• Click the Create New App button on the top right.
• Enter a meaningful name for your app along with a description if necessary (these can be anything but will enable you to identify them if, for example, you are using multiple apps for different connections).
• The OAuth redirect URIs field will need the address to your websites connection page.  This can be found on the settings page in the WordPress admin area (WooCommerce > Settings > Integrations > FreeAgent), labelled OAuth redirect URI.  The existing URIs within this field can be left in place (these are used for testing purposes) and you can add your own URI on a new line.  It will not cause issues if you delete the existing URIs.
• Finish the process by clicking Create App.
• On the next screen you will be presented with your application credentials.  Copy both the OAuth Identifier and OAuth Secret over to your FreeAgent settings page in the WordPress admin and click Save Changes.  This will store these values in your database.
• Once the page has reloaded, click Connect to FreeAgent and proceed to sign in and approve your new application.

Settings Screen

↑ Back to top

Visit Woocommerce > Settings > Integration to manage the extension.

Connection Options

↑ Back to top

• Connect FreeAgent: Asks you to log in to your FreeAgent account and allow WooCommerce access.
• Disconnect FreeAgent: Disconnects the current FreeAgent account, stopping any future contacts/invoices from being created and disabling synchronization until reconnected.

Invoice Options

↑ Back to top

• Create Invoices (detailed mode only): Automatically create invoices when orders are created. If unchecked, invoices can only be manually created on the order screen.
• Send Invoices (detailed mode only): Sends created invoices to the contact via FreeAgent.
• Mark Invoices as sent: Mark invoices as “sent” (open) rather than “Draft” when created.
• FreeAgent User Email Address: The “from” email address for sending emails from FreeAgent (required if “Send Invoices” is checked).
• Custom Invoice Reference: Designate a custom reference for FreeAgent invoices, which must include the order ID somewhere in the reference.
• Set Accounting Category for Invoices: Select the income category to be used for invoices (defaults to “Sales”).  Use the “Reload categories” button if you update your categories in FreeAgent and they are not yet reflected here.
• Set Payment Terms in Days: Sets the number of days before an invoice becomes overdue.
• Set Default X Item Type (detailed mode only): Set the item type to appear on the invoice for products, shipping and fees.
• Automatically Apply Payments to Invoices (detailed mode only): Apply manual payments to FreeAgent invoices when order payment is taken in WooCommerce.
• Select Bank Account: Choose which bank account will be used when adding payments to FreeAgent (a bank account and contact named “WooCommerce” will be generated in summarized mode).  Use the “Reload bank accounts” button if you update your accounts in FreeAgent and they are not yet reflected here.
• Select Payment Option: If you have payment options setup for your FreeAgent invoices you can set which to use here.  If this is not set here or setup properly in your FreeAgent account this will be ignored.
• VAT MOSS (summarized mode only): Mark all products as digital services eligible for VAT MOSS.

Synchronization Options (detailed mode only)

↑ Back to top

• Synchronize Automatically: Periodically check FreeAgent invoice statuses and references to ensure they match WooCommerce order data.
• Synchronization Frequency: Determine how often FreeAgent invoices will be synchronized with WooCommerce orders.
• Synchronize Now: Manually run the synchronization process.

Usage

↑ Back to top

Summarized Mode

↑ Back to top

After activating the plugin, connect to your FreeAgent account as described above. Adjust the plugin options as required, and your first summarized invoice will appear in FreeAgent at the end of the day. The structure of your daily invoices will be as follows:

• Separate invoices for each currency if operating with multi-currency.
• Invoices for all goods and services sold outside the EU, organized by tax rate.
• Invoices for services sold to the EU, VAT marked as “Reverse Charge”.
• Invoices for products marked as “EC VAT MOSS,” organized by billing country and tax rate (Important: invoices will only be created if the tax rate matches a valid option for the billing country in FreeAgent).

Detailed mode

↑ Back to top

Automatically creating invoices

If Create Invoices is set then a new invoice will be created in FreeAgent every time a new order is created. A contact will also be generated using the customer’s details.  If Mark Invoices as sent is selected then the invoice status will be updated to “Open” (as per FreeAgent).  The invoice status will be shown alongside the order on the Woocommerce > Orders screen: When an order is updated the changes made to any items on the order (along with any additional items/charges) will be reflected in the FreeAgent invoice, provided that it is editable at the time.

Manually creating invoices

If you are not automatically generating invoices, a button for these actions will become available to you on the WooCommerce > Orders screen: Also under Order Actions on the individual order edit screen:

Synchronizing Payments

If Synchronize Automatically is enabled, a manual payment is added to the corresponding FreeAgent invoice, marking it as “Paid” when a WooCommerce order status is updated to processing/completed. A periodic check will ensure WooCommerce order statuses match FreeAgent invoice statuses, updating order status if necessary. Invoice ItemsEach order item is added to the invoice as a separate line item with its corresponding tax rate.

FreeAgent Metabox

A metabox is added to the edit order screen for viewing the corresponding FreeAgent invoice and its status (in summarized mode, this links to the daily invoice).

Customization

↑ Back to top

FreeAgent Sync for WooCommerce comes with action and filter hooks for your customization needs. For more information on using hooks in WordPress, see Plugin API.

Action Hooks

↑ Back to top

FAQ

↑ Back to top

My application has disconnected from my FreeAgent account, what can I do?

↑ Back to top

If the application encounters an error and cannot establish a connection, the site admin will receive an email and a notice will be displayed in the WordPress admin area. In this event, visit WooCommerce > Settings > Integrations > FreeAgent and re-connect your application. If the issue persists, it is likely that your WooCommerce store is reaching limits provided by the FreeAgent API. To avoid this, you can:

• Consider switching to Summarized Mode, since this reduces the number of requests to FreeAgent, helping avoid API rate limit issues (recommended).
• Consider disabling Synchronize Automatically, since this option repeatedly checks open invoices, comparing them to orders until the invoice is marked as paid.

If the issue persists, or you need assistance with the above steps, please get in touch via a support request. Activating Enable Detailed Debugging on the settings page and providing a log file where your application has failed will help us to track down the issue more quickly.

How can I match up my Stripe payments with my invoices/sales entries when they’re a different amount?

↑ Back to top

Stripe deducts fees before releasing funds to your bank account, so you should explain the incoming transaction as the full invoice amount before fees. This creates a negative transaction in your bank account to explain as desired.