Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Sales

Invoices, estimates and credit notes, and sending them. Conventions for ids, money, paging and errors are on Working with the tools.

Invoices

ToolKindWhat it doesKey parameters
list_invoicesreadInvoices with reference, contact, dates, status (Draft, Open, Overdue, Paid and so on), total_value and due_valueview, contact_id, project_id, sort, updated_since, with_items, page, per_page
get_invoicereadOne invoice in full, with its line items, totals, VAT, what is paid and due, and its payment linkid
create_invoicewriteCreate a draft invoice from line items, a project’s unbilled time and expenses, or both. Returns it with its id and totalscontact_id, items, invoice fields (below)
update_invoicewriteChange only the fields given. items adds lines; an item with id changes that line, and with id and delete: true removes it. Sent invoices may be locked: mark_as_draft firstid, invoice fields
delete_invoicewrite, destructiveDelete a draft invoice. Sent invoices are refused: cancel them with invoice_action mark_as_cancelled, or issue a credit noteid
invoice_actionwrite, destructiveMove an invoice through its life (below)id, action
list_recurring_invoicesreadRecurring invoice profiles FreeAgent invoices from on a schedule, with frequency, next_recurs_on and statuscontact_id, view: draft, active or inactive (default all)

list_invoices view: all (default), recent_open_or_overdue, open, overdue, open_or_overdue, draft, paid, scheduled_to_email, thank_you_emails, reminder_emails, or last_N_months such as last_3_months. open_or_overdue shows what customers owe. sort is created_at (default) or updated_at, prefixed - for newest first.

Invoice fields

FieldMeaning
contact_idThe customer. Required on create
itemsLine items (below), up to 100
dated_onThe invoice date. Default on create: today
payment_terms_in_daysDays until due; 0 means due on receipt. Default on create: the contact’s payment terms, otherwise 30
due_onA fixed due date instead of payment terms
referenceInvoice number. Default: the next in sequence
currencyISO 4217 code. Default: the company’s currency
commentsText shown on the invoice, such as payment details or thanks
discount_percent, po_reference, project_id
ec_statusUK/Non-EC (default), EC Goods, EC Services, Reverse Charge or EC VAT MOSS
include_timeslips, include_expensesA project’s unbilled time and rebillable expenses; see below. Need project_id
extraAny other invoice field by FreeAgent’s name, such as {"payment_methods": {"stripe": true}}

An invoice stays a draft until invoice_action mark_as_sent or send_document_email.

Invoicing a project’s time and expenses

create_invoice with project_id adds:

  • include_timeslips: the project’s unbilled time, grouped as billed_grouped_by_single_timeslip, billed_grouped_by_timeslip, billed_grouped_by_timeslip_task or billed_grouped_by_timeslip_date.
  • include_expenses: its rebillable expenses, grouped as billed_grouped_by_single_expense or billed_grouped_by_expense.

Invoice actions

invoice_action action:

ActionEffect
mark_as_sentMarks it sent without emailing it. Also re-opens a cancelled invoice
mark_as_draftBack to draft, so it can be edited
mark_as_scheduledTo be emailed by FreeAgent
mark_as_cancelledWrites off an unpaid invoice
convert_to_credit_noteMakes it a draft negative invoice
duplicateA new draft copy dated today

To email an invoice, use send_document_email. To record a payment, explain the bank transaction with paid_invoice_id (Banking).

Estimates

ToolKindWhat it doesKey parameters
list_estimatesreadEstimates and quotes with reference, contact, status and totalsview: all (default), recent, draft, non_draft, sent, approved, rejected or invoiced; contact_id, project_id, from_date, to_date, updated_since, with_items, page, per_page
get_estimatereadOne estimate or quote in full, with its itemsid
create_estimatewriteCreate a draft estimate, quote or proposal from line itemscontact_id, reference (such as EST-012), items, estimate_type (Estimate (default), Quote or Proposal), dated_on (default today), currency, discount_percent, ec_status, notes, project_id, extra
estimate_actionwritemark_as_sent, mark_as_draft, mark_as_approved, mark_as_rejected, convert_to_invoice (makes a draft invoice from it) or duplicateid, action

Credit notes

ToolKindWhat it doesKey parameters
list_credit_notesreadCredit notes with reference, contact, status and valuesview: all (default), recent_open_or_overdue, open, overdue, open_or_overdue, draft, refunded or last_N_months; contact_id, project_id, updated_since, page, per_page
get_credit_notereadOne credit note in full, with its itemsid
create_credit_notewriteA draft credit note for a customer, for example to credit part of an invoice. Prices are positivecontact_id, items, dated_on (default today), payment_terms_in_days (default 0), reference, currency, comments, project_id, extra

Apply a credit note to an invoice or refund it in FreeAgent, or with api_request on credit_note_reconciliations (Any other endpoint).

Line items

Each item of items on invoices, estimates and credit notes:

FieldMeaning
descriptionWhat was sold, as it reads on the document. Required for a new item
quantityHow many, such as 7.5. Default for a new item: 1
pricePrice per unit before VAT, such as 80
item_typeHours, Days, Weeks, Months, Years, Products, Services, Training, Expenses, Comment, Bills, Discount, Credit, VAT or Stock; leave out for no unit
categoryIncome category as a nominal code, such as 001 (Sales). Default: the company’s sales category
sales_tax_rateVAT percentage, such as 20, 5 or 0. Default: from the contact’s charge_sales_tax setting; on an estimate, the company’s standard rate, or 0 for a contact never charged VAT
sales_tax_statusTAXABLE, EXEMPT or OUT_OF_SCOPE
id, deleteOn update: the id of an existing item to change, and delete: true to remove it. Leave id out to add an item. An existing item keeps every field the update does not give

Sending and documents

ToolKindWhat it doesKey parameters
send_document_emailwriteEmail an invoice, estimate or credit note to the customer through FreeAgent, with a link to view (and pay) it. A draft invoice is marked as sentdocument (invoice, estimate or credit_note), id, subject and body, or use_template; to, from, email_to_sender
get_document_pdfreadThe PDF of an invoice, estimate or credit note, as an embedded application/pdf resource, for example to attach or savedocument, id
list_email_addressesreadThe verified addresses FreeAgent can send from, for send_document_email’s fromnone
list_price_list_itemsreadThe price list: saved products and services with code, description, price, unit and VAT, to reuse as invoice linessort: created_at, code or updated_at; page, per_page

send_document_email details:

  • to is comma-separated addresses. Default: the contact’s billing email, otherwise its main email.
  • from must be a verified address from list_email_addresses. Default: FreeAgent’s.
  • use_template: true sends FreeAgent’s own email template instead of subject and body. FreeAgent adds the view and pay link either way.
  • email_to_sender sends a copy to the sender. Default: true.