Bills

Minimum access level: Bills, unless stated otherwise.

If you created the integration prior to 19th May 2021, you will need to supply the header FreeAgent-Features: bill_items to access the new bills schema.

Documentation for the old schema can be found at Bills (deprecated) for existing integrators

Attributes

Required Attribute Description Kind
url The unique identifier for the bill URI
✔ contact Contact being billed URI
✔ reference Free-text reference String
✔ dated_on Date of bill Date
✔ due_on Due date of bill Date
paid_on Date of most recent payment, only returned for fully paid bills and bill refunds [Learn more about bill refunds] Date
status

Bill's payment status, determined based on the presence of associated bank transaction explanations. Can be one of the following:

  • Zero Value
  • Open
  • Paid
  • Overdue
  • Refunded - if the bill's total value is a negative number (making it a bill refund), and it's been fully paid

 String
long_status

Bill's payment status along with the due date as a relative date to 'today'

For example: Open - due in 21 days

String
currency

Bill's currency

Defaults to the company's native currency 		String
total_value

Total value of the bill, calculated from the bill item totals

 Decimal
exchange_rate

Rate at which bill amount is converted into company's native currency

 Decimal
ec_status Bill's VAT status for reporting purposes. One of the following:

  • UK/Non-EC
  • EC Goods
  • EC Services

Please note that EC Goods is no longer a valid option if the bill is dated 1/1/2021 or later and the company is based in Great Britain, following the UK's withdrawal from the EU.

You should use EC Services for reverse charge bills.

 String
comments Free-text comments String
project Project billed for URI
? rebill_type

One of the following, if rebilling a project:

  • cost
  • markup
  • price
 String
? rebill_factor

How much to rebill for

Required when rebill_type is markup or price 		Decimal
rebill_to_project Same as project URI
recurring

Frequency at which the bill will recur. Can be one of the following:

  • Weekly
  • Two Weekly
  • Four Weekly
  • Two Monthly
  • Quarterly
  • Biannually
  • Annually
  • 2-Yearly

 String
recurring_end_date When the bill should stop recurring in YYYY-MM-DD format Date
attachment

Explanation attachment (max 5MB), in the following format:

  • data (binary data of the file being attached encoded as base64)
  • file_name
  • description
  • content_type can be one of the following:
    • image/png
    • image/x-png
    • image/jpeg
    • image/jpg
    • image/gif
    • application/x-pdf
 Object
✔ bill_items Array of bill item data structures. See Bill Item Attributes. At present only one bill item is allowed per bill Array
created_at Creation of the bill resource (UTC) Timestamp
updated_at When the bill resource was last updated (UTC) Timestamp
Sales tax attributes – see Sales Tax for which attribute should be included
sales_tax_value Total value of sales tax Decimal
second_sales_tax_value [Universal accounts only] Total value of second sales tax Decimal

Bill Item Attributes

Required Attribute Description Kind
url The unique identifier for the invoice item URI
bill The parent bill of the item URI
✔ category Accounting category of the bill item URI
✔ description Description of the bill item String
✔ total_value

Value of the item

 Decimal
manual_sales_tax_amount Amount of sales tax for the bill item, in the company's native currency Decimal
sales_tax_rate One of the standard sales tax rates Decimal
second_sales_tax_rate [Universal accounts only] One of the standard second sales tax rates Decimal
sales_tax_status Indicates whether the item is TAXABLE, EXEMPT or OUT_OF_SCOPE for sales tax String
second_sales_tax_status [Universal accounts only] Sales tax period defines a second sales tax String
unit `Stock` for stock items, otherwise leave blank for 'No Unit' String
quantity

Quantity of the unit

Presently this will be defaulted to 1 		Decimal
? stock_item Stock item being invoiced Required when item_type is set to stock URI
depreciation_schedule The depreciation schedule of the item
project The project being billed URI

List all bills

GET https://api.freeagent.com/v2/bills

Input

View Filters

GET https://api.freeagent.com/v2/bills?view=open
  • all: (default)
  • open: Show only open bills.
  • overdue: Show only overdue bills.
  • open_or_overdue: Show only open or overdue bills.
  • paid: Show only paid bills.
  • recurring: Show only recurring bills.

Date Filters

GET https://api.freeagent.com/v2/bills?from_date=2012-01-01&to_date=2012-03-31

GET https://api.freeagent.com/v2/bills?updated_since=2017-05-22T09:00:00.000Z
  • from_date
  • to_date
  • updated_since

Response

Status: 200 OK

{ "bills":[{
  "url":"https://api.freeagent.com/v2/bills/1",
  "contact":"https://api.freeagent.com/v2/contacts/1",
  "reference":"acsad",
  "dated_on":"2020-07-28",
  "due_on":"2020-08-27",
  "currency":"GBP",
  "total_value":"213.0",
  "exchange_rate":"0.61342",
  "paid_value":"200.0",
  "due_value":"13.0",
  "sales_tax_value":"-35.5",
  "status":"Open",
  "long_status": "Open - due in about 1 month",
  "rebill_type": "price",
  "rebill_factor": "20",
  "rebill_to_project": "https://api.freeagent.com/v2/projects/1",
  "rebilled_on_invoice_item": "https://api.freeagent.com/v2/invoices/1",
  "updated_at":"2020-07-28T12:43:36Z",
  "created_at":"2020-07-28T12:43:36Z",
  "attachment":
    {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
        "content_type":"image/png",
        "file_name":"barcode.png",
        "file_size":7673
    }
  }
]}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bills type="array">
    <bill>
      <url>https://api.freeagent.com/v2/bills/1</url>
      <contact>https://api.freeagent.com/v2/contacts/1</contact>
      <reference>acsad</reference>
      <dated-on type="date">2020-07-28</dated-on>
      <due-on type="date">2020-08-27</due-on>
      <currency>GBP</currency>
      <total-value type="decimal">213.0</total-value>
      <exchange-rate type="decimal">0.61342</exchange-rate>
      <paid-value type="decimal">200.0</paid-value>
      <due-value type="decimal">13.0</due-value>
      <sales-tax-value type="decimal">-35.5</sales-tax-value>
      <sales-tax-rate type="decimal">20.0</sales-tax-rate>
      <status>Open</status>
      <long-status>Open - due in about 1 month</long-status>
      <rebill-type>price</rebill-type>
      <rebill-factor type="decimal">20</rebill-factor>
      <rebill-to-project>https://api.freeagent.com/v2/projects/1</rebill-to-project>
      <rebilled-on-invoice-item>https://api.freeagent.com/v2/invoices/1</rebilled-on-invoice-item>
      <updated-at type="datetime">2020-07-28T12:43:36Z</updated-at>
      <created-at type="datetime">2020-07-28T12:43:36Z</created-at>
      <attachment>
        <url>https://api.freeagent.com/v2/attachments/3</url>
        <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1314281298&amp;Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
        <content-type>image/png</content-type>
        <file-name>barcode.png</file-name>
        <file-size type="integer">7673</file-size>
      </attachment>
    </bill>
  </bills>
</freeagent>
Show as JSON

List all bills with nested bill items

You can include bill items nested into the list of bills which increases request size but removes the need to request the bills separately to see bill item information.

GET https://api.freeagent.com/v2/bills?nested_bill_items=true

Response

Status: 200 OK

{ "bills":[{
  "url":"https://api.freeagent.com/v2/bills/1",
  "contact":"https://api.freeagent.com/v2/contacts/1",
  "reference":"REF 001",
  "dated_on":"2020-07-28",
  "due_on":"2020-08-27",
  "currency":"GBP",
  "total_value":"213.0",
  "exchange_rate":"0.61342",
  "paid_value":"200.0",
  "due_value":"13.0",
  "sales_tax_value":"-35.5",
  "status":"Open",
  "long_status": "Open - due in about 1 month",
  "rebill_type": "price",
  "rebill_factor": "20",
  "rebill_to_project": "https://api.freeagent.com/v2/projects/1",
  "rebilled_on_invoice_item": "https://api.freeagent.com/v2/invoices/1",
  "updated_at":"2020-07-28T12:43:36Z",
  "created_at":"2020-07-28T12:43:36Z",
  "attachment":
    {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
        "content_type":"image/png",
        "file_name":"barcode.png",
        "file_size":7673
    },
  "bill_items":
    [
      {
        "url":"https://api.freeagent.com/v2/bill_items?bill=https://api.freeagent.com/v2/bills/12",
        "bill":"https://api.freeagent.com/v2/bills/12",
        "description":"Alex Gregory - Bill REF 001",
        "category":"https://api.freeagent.com/v2/categories/285",
        "quantity":1.5,
        "unit":"Stock",
        "total_value":34.65,
        "sales_tax_status":"TAXABLE",
        "second_sales_tax_status":"TAXABLE",
        "sales_tax_rate":20.0,
        "sales_tax_value":6.93,
        "second_sales_tax_rate":0.0,
        "second_sales_tax_value":0.0,
        "stock_item":"https://api.freeagent.com/v2/stock_item/42"
      }
    ]
  }
]}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bills type="array">
    <bill>
      <url>https://api.freeagent.com/v2/bills/1</url>
      <contact>https://api.freeagent.com/v2/contacts/1</contact>
      <reference>REF100</reference>
      <dated-on type="date">2020-07-28</dated-on>
      <due-on type="date">2020-08-27</due-on>
      <currency>GBP</currency>
      <total-value type="decimal">213.0</total-value>
      <exchange-rate type="decimal">0.61342</exchange-rate>
      <paid-value type="decimal">200.0</paid-value>
      <due-value type="decimal">13.0</due-value>
      <sales-tax-value type="decimal">-35.5</sales-tax-value>
      <sales-tax-rate type="decimal">20.0</sales-tax-rate>
      <status>Open</status>
      <long-status>Open - due in about 1 month</long-status>
      <rebill-type>price</rebill-type>
      <rebill-factor type="decimal">20</rebill-factor>
      <rebill-to-project>https://api.freeagent.com/v2/projects/1</rebill-to-project>
      <rebilled-on-invoice-item>https://api.freeagent.com/v2/invoices/1</rebilled-on-invoice-item>
      <updated-at type="datetime">2020-07-28T12:43:36Z</updated-at>
      <created-at type="datetime">2020-07-28T12:43:36Z</created-at>
      <attachment>
        <url>https://api.freeagent.com/v2/attachments/3</url>
        <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1314281298&amp;Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
        <content-type>image/png</content-type>
        <file-name>barcode.png</file-name>
        <file-size type="integer">7673</file-size>
      </attachment>
      <bill-items type="array">
        <bill-item>
          <bill>https://api.freeagent.com/v2/bills/12</bill>
          <category>https://api.freeagent.com/v2/categories/285</category>
          <description>Alex Gregory - Bill REF100</description>
          <quantity>1.5</quantity>
          <sales_tax_rate>20.0</sales_tax_rate>
          <sales_tax_status>TAXABLE</sales_tax_status>
          <sales_tax_value>6.93</sales_tax_value>
          <second_sales_tax_rate>0.0</second_sales_tax_rate>
          <second_sales_tax_status>TAXABLE</second_sales_tax_status>
          <second_sales_tax_value>0.0</second_sales_tax_value>
          <stock_item>https://api.freeagent.com/v2/stock_item/42</stock_item>
          <total_value>34.65</total_value>
          <unit>Stock</unit>
          <url>https://api.freeagent.com/v2/bill_items?bill=https://api.freeagent.com/v2/bills/12</url>
        </bill-item>
      </bill-items>
    </bill>
  </bills>
</freeagent>
Show as JSON

Get a single bill

GET https://api.freeagent.com/v2/bills/:id

Response

Status: 200 OK

{ "bill":{
  "url":"https://api.freeagent.com/v2/bills/1",
  "contact":"https://api.freeagent.com/v2/contacts/1",
  "reference":"REF100",
  "dated_on":"2020-09-14",
  "due_on":"2020-10-14",
  "currency":"GBP",
  "total_value":"100.0",
  "exchange_rate":"0.673193",
  "paid_value":"80.0",
  "due_value":"20.0",
  "sales_tax_value":"-16.67",
  "status":"Open",
  "long_status":"Open - due in about 1 month",
  "rebill_type": "price",
  "rebill_factor": "20",
  "rebill_to_project": "https://api.freeagent.com/v2/projects/1",
  "rebilled_on_invoice_item": "https://api.freeagent.com/v2/invoices/1",
  "updated_at":"2020-09-14T16:00:41Z",
  "created_at":"2020-09-14T16:00:41Z",
  "attachment":
    {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
        "content_type":"image/png",
        "file_name":"barcode.png",
        "file_size":7673
    },
    "bill_items":
    [
      {
        "url":"https://api.freeagent.com/v2/bill_items?bill=https://api.freeagent.com/v2/bills/12",
        "bill":"https://api.freeagent.com/v2/bills/12",
        "description":"Alex Gregory - Bill REF100",
        "category":"https://api.freeagent.com/v2/categories/285",
        "quantity":1.5,
        "unit":"Stock",
        "total_value":34.65,
        "sales_tax_status":"TAXABLE",
        "second_sales_tax_status":"TAXABLE",
        "sales_tax_rate":20.0,
        "sales_tax_value":6.93,
        "second_sales_tax_rate":0.0,
        "second_sales_tax_value":0.0,
        "stock_item":"https://api.freeagent.com/v2/stock_item/42"
      }
    ]
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bill>
    <url>https://api.freeagent.com/v2/bills/1</url>
    <contact>https://api.freeagent.com/v2/contacts/1</contact>
    <reference>REF100</reference>
    <dated-on type="date">2020-09-14</dated-on>
    <due-on type="date">2020-10-14</due-on>
    <currency>GBP</currency>
    <total-value type="decimal">100.0</total-value>
    <paid-value type="decimal">80.0<paid-value>
    <exchange-rate type="decimal">0.67319</exchange-rate>
    <due-value type="decimal">20.0</due-value>
    <sales-tax-value type="decimal">-16.67</sales-tax-value>
    <sales-tax-rate type="decimal">20.0</sales-tax-rate>
    <status>Open</status>
    <long-status>Open - due in about 1 month</long-status>
    <rebill-type>price</rebill-type>
    <rebill-factor type="decimal">20</rebill-factor>
    <rebill-to-project>https://api.freeagent.com/v2/projects/1</rebill-to-project>
    <rebilled-on-invoice-item>https://api.freeagent.com/v2/invoices/1</rebilled-on-invoice-item>
    <updated-at type="datetime">2020-09-14T16:00:41Z</updated-at>
    <created-at type="datetime">2020-09-14T16:00:41Z</created-at>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1314281298&amp;Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
      <content-type>image/png</content-type>
      <file-name>barcode.png</file-name>
      <file-size type="integer">7673</file-size>
    </attachment>
    <bill-items type="array">
      <bill-item>
        <bill>https://api.freeagent.com/v2/bills/12</bill>
        <category>https://api.freeagent.com/v2/categories/285</category>
        <description>Alex Gregory - Bill REF100</description>
        <quantity>1.5</quantity>
        <sales_tax_rate>20.0</sales_tax_rate>
        <sales_tax_status>TAXABLE</sales_tax_status>
        <sales_tax_value>6.93</sales_tax_value>
        <second_sales_tax_rate>0.0</second_sales_tax_rate>
        <second_sales_tax_status>TAXABLE</second_sales_tax_status>
        <second_sales_tax_value>0.0</second_sales_tax_value>
        <stock_item>https://api.freeagent.com/v2/stock_item/42</stock_item>
        <total_value>34.65</total_value>
        <unit>Stock</unit>
        <url>https://api.freeagent.com/v2/bill_items?bill=https://api.freeagent.com/v2/bills/12</url>
      </bill-item>
    </bill-items>
  </bill>
</freeagent>
Show as JSON
GET https://api.freeagent.com/v2/bills?contact=https://api.freeagent.com/v2/contacts/2

GET https://api.freeagent.com/v2/bills?project=https://api.freeagent.com/v2/projects/2

Create a bill

POST https://api.freeagent.com/v2/bills

Payload should have a root bill element, containing elements listed under Attributes.

Response

Status: 201 Created
Location: https://api.freeagent.com/v2/bills/12

{ "bill":{
  "url":"https://api.freeagent.com/v2/bills/12",
  "contact":"https://api.freeagent.com/v2/contacts/1",
  "reference":"REF100",
  "dated_on":"2020-09-14",
  "due_on":"2020-10-14",
  "currency":"GBP",
  "total_value":"100.0",
  "exchange_rate":"0.67319",
  "paid_value":"80.0",
  "due_value":"20.0",
  "sales_tax_value":"-16.67",
  "status":"Open",
  "long_status":"Open - due in about 1 month",
  "rebill_type": "price",
  "rebill_factor": "20",
  "rebill_to_project": "https://api.freeagent.com/v2/projects/1",
  "rebilled_on_invoice_item": "https://api.freeagent.com/v2/invoices/1",
  "updated_at":"2020-09-14T16:00:41Z",
  "created_at":"2020-09-14T16:00:41Z",
  "attachment":
    {
        "url":"https://api.freeagent.com/v2/attachments/3",
        "content_src":"https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&Expires=1314281186&Signature=GFAKDo%2Bi%2FsUMTYEgg6ZWGysB4k4%3D",
        "content_type":"image/png",
        "file_name":"barcode.png",
        "file_size":7673
    },
  "bill_items":
    [
      {
        "url":"https://api.freeagent.com/v2/bill_items?bill=https://api.freeagent.com/v2/bills/12",
        "bill":"https://api.freeagent.com/v2/bills/12",
        "description":"Alex Gregory - Bill REF100",
        "category":"https://api.freeagent.com/v2/categories/285",
        "quantity":1.5,
        "unit":"Stock",
        "total_value":34.65,
        "sales_tax_status":"TAXABLE",
        "second_sales_tax_status":"TAXABLE",
        "sales_tax_rate":20.0,
        "sales_tax_value":6.93,
        "second_sales_tax_rate":0.0,
        "second_sales_tax_value":0.0,
        "stock_item":"https://api.freeagent.com/v2/stock_item/42"
      }
    ]
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bill>
    <url>https://api.freeagent.com/v2/bills/12</url>
    <contact>https://api.freeagent.com/v2/contacts/1</contact>
    <reference>REF100</reference>
    <dated-on type="date">2020-09-14</dated-on>
    <due-on type="date">2020-10-14</due-on>
    <currency>GBP</currency>
    <total-value type="decimal">100.0</total-value>
    <exchange-rate>0.93183</exchanage-rate>
    <paid-value type="decimal">80.0</paid-value>
    <due-value type="decimal">20.0</due-value>
    <sales-tax-value type="decimal">-16.67</sales-tax-value>
    <sales-tax-rate type="decimal">20.0</sales-tax-rate>
    <status>Open</status>
    <long-status>Open - due in about 1 month</long-status>
    <rebill-type>price</rebill-type>
    <rebill-factor type="decimal">20</rebill-factor>
    <rebill-to-project>https://api.freeagent.com/v2/projects/1</rebill-to-project>
    <rebilled-on-invoice-item>https://api.freeagent.com/v2/invoices/1</rebilled-on-invoice-item>
    <updated-at type="datetime">2020-09-14T16:00:41Z</updated-at>
    <created-at type="datetime">2020-09-14T16:00:41Z</created-at>
    <attachment>
      <url>https://api.freeagent.com/v2/attachments/3</url>
      <content-src>https://s3.amazonaws.com/freeagent-dev/attachments/1/original.png?AWSAccessKeyId=1K3MW21E6T8KWBY84B02&amp;Expires=1314281298&amp;Signature=jhGeAgqdnDwyFKHJoPI6AKU%2Fb2s%3D</content-src>
      <content-type>image/png</content-type>
      <file-name>barcode.png</file-name>
      <file-size type="integer">7673</file-size>
    </attachment>
    <bill-items type="array">
      <bill-item>
        <bill>https://api.freeagent.com/v2/bills/12</bill>
        <category>https://api.freeagent.com/v2/categories/285</category>
        <description>Alex Gregory - Bill REF100</description>
        <quantity>1.5</quantity>
        <sales_tax_rate>20.0</sales_tax_rate>
        <sales_tax_status>TAXABLE</sales_tax_status>
        <sales_tax_value>6.93</sales_tax_value>
        <second_sales_tax_rate>0.0</second_sales_tax_rate>
        <second_sales_tax_status>TAXABLE</second_sales_tax_status>
        <second_sales_tax_value>0.0</second_sales_tax_value>
        <stock_item>https://api.freeagent.com/v2/stock_item/42</stock_item>
        <total_value>34.65</total_value>
        <unit>Stock</unit>
        <url>https://api.freeagent.com/v2/bill_items?bill=https://api.freeagent.com/v2/bills/12</url>
      </bill-item>
    </bill-items>
  </bill>
</freeagent>
Show as JSON

Update a bill

PUT https://api.freeagent.com/v2/bills/:id

Payload should have a root bill element, containing elements listed under Attributes that should be updated.

Response

Status: 200 OK

Delete a bill

DELETE https://api.freeagent.com/v2/bills/:id

Response

Status: 200 OK