FreeAgent – Gotchas

FreeAgent has no dedicated bill credit note object — a bill credit note is a FreeAgent bill with a negative total. This resource does not support listing: FreeAgent has no server-side filter for credit notes, and isolating them client-side from the bills list would break that list's pagination. Fetch a credit note by id (a bill id whose total is not negative returns 404), and discover credit notes through the bills resource, where they appear as bills with a negative total.

FreeAgent stores credit amounts as negative numbers; on read every amount is normalized to positive — the header totals total_amount, sub_total, total_tax and balance, and each line_items[].total_amount (total_tax is derived as total_amount − sub_total, since FreeAgent returns no tax field on a bill header). Header sub_total is net; a line's total_amount is gross (tax-inclusive). A line's tax rate is the FreeAgent sales-tax percentage, exposed as line_items[].tax_rate.code; FreeAgent has no tax-rate objects, so tax_rate.id is not available.

status reflects payment state: posted while a balance is outstanding, paid once fully settled. There is no draft state. remaining_credit, allocations, tax_code, subsidiary, tracking_categories, custom_fields and row_version are not populated.

A bill credit note is created as a FreeAgent bill with negative line amounts, producing a record with a negative total. Amounts are sent positive and stored negative.

FreeAgent requires reference and a ledger account on every line (line_items[].ledger_account.id); a create without them is rejected. due_date is not part of the bill credit note; FreeAgent's required due date is set to date_issued. A line's tax rate is supplied as a percentage via line_items[].tax_rate.code (FreeAgent has no tax-rate objects, so tax_rate.id is ignored).

On update, existing lines can be edited or removed (send the surviving lines with their id; a dropped line is deleted), but a new line cannot be added — FreeAgent requires every line on an update to reference an existing one.

status cannot be set — it is derived from payment state (posted until fully settled, then paid). There is no draft state.

In FreeAgent, newly created customers will not appear in customer list responses until an invoice has been assigned to them. This is because FreeAgent only classifies contacts as customers once they have associated invoices. See Set up a contact as a customer or a supplier for more details.

balance reflects the contact's net position across both sales invoices and purchase bills. FreeAgent does not keep a separate ledger balance for a contact's customer role versus its supplier role, so if the same contact is also used as a supplier, an outstanding bill against them lowers balance (or makes it negative) rather than being excluded. Draft invoices and bills are not included until posted.

You can create customer contacts, but they will not be visible in customer list responses until an invoice is assigned to them. FreeAgent only classifies contacts as customers after they have associated transactions. See Set up a contact as a customer or a supplier for more information.

balance reflects the contact's net position across both sales invoices and purchase bills. FreeAgent does not keep a separate ledger balance for a contact's customer role versus its supplier role, so if the same contact is also used as a supplier, an outstanding bill against them lowers balance (or makes it negative) rather than being excluded. Draft invoices and bills are not included until posted.

We use price list items from FreeAgent to support invoice items. To access stock items, please use the Proxy API.

Related resources:

• Price List Items
• Stock Items
• Stock Items via Proxy API

We use price list items from FreeAgent to support invoice items. To access stock items, please use the Proxy API.

Related resources:

• Price List Items
• Stock Items
• Stock Items via Proxy API

We use price list items from FreeAgent to support invoice items. To access stock items, please use the Proxy API.

Related resources:

• Price List Items
• Stock Items
• Stock Items via Proxy API

Line items must balance to zero — FreeAgent rejects the whole entry otherwise, rather than accepting it and leaving the books unbalanced. Only ledger_account, total_amount, type and description are supported per line; a category that requires an associated user, stock item, capital asset, property, or contact (used for opening balances and a handful of specialised ledger accounts) cannot be targeted through this connector.

Line items must balance to zero. Only ledger_account, total_amount, type and description are supported per line; a category that requires an associated user, stock item, capital asset, property, or contact cannot be targeted through this connector. A line included in the update is modified in place; lines from the existing entry that are left out of the request are not removed.

FreeAgent's Profit and Loss API has a date range limitation. The specified period must be 12 months or less, or contained within a single accounting year. Periods that exceed 12 months and span multiple accounting years will return an error.