Bills

Minimum access level: Bills, unless stated otherwise.

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

Use negative value for a Bill Refund
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
category Bill's accounting category URI
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 true if the bill should recur, false otherwise Boolean
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
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_rate One of the standard sales tax rates Decimal
sales_tax_value Total value of sales tax Decimal
second_sales_tax_rate [Universal accounts only] One of the standard second sales tax rates Decimal
second_sales_tax_value [Universal accounts only] Total value of second sales tax Decimal
manual_sales_tax_amount Manual amount of sales tax 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] Similar to sales_tax_status, returned only if the relevant sales tax period defines a second sales tax String

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",
  "category":"https://api.freeagent.com/v2/categories/285",
  "reference":"acsad",
  "dated_on":"2011-07-28",
  "due_on":"2011-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",
  "sales_tax_rate":"20.0",
  "sales_tax_status": "TAXABLE",
  "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":"2011-07-28T12:43:36Z",
  "created_at":"2011-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>
      <category>https://api.freeagent.com/v2/categories/285</category>
      <reference>acsad</reference>
      <dated-on type="date">2011-07-28</dated-on>
      <due-on type="date">2011-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">2011-07-28T12:43:36Z</updated-at>
      <created-at type="datetime">2011-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

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",
  "category":"https://api.freeagent.com/v2/categories/285",
  "reference":"sdasd",
  "dated_on":"2011-09-14",
  "due_on":"2011-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",
  "sales_tax_rate":"20.0",
  "sales_tax_status": "TAXABLE",
  "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":"2011-09-14T16:00:41Z",
  "created_at":"2011-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
    }
  }
}
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>
    <category>https://api.freeagent.com/v2/categories/285</category>
    <reference>sdasd</reference>
    <dated-on type="date">2011-09-14</dated-on>
    <due-on type="date">2011-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">2011-09-14T16:00:41Z</updated-at>
    <created-at type="datetime">2011-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>
</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":{
  "contact":"https://api.freeagent.com/v2/contacts/1",
  "category":"https://api.freeagent.com/v2/categories/285",
  "reference":"sdasd",
  "dated_on":"2011-09-14",
  "due_on":"2011-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",
  "sales_tax_rate":"20.0",
  "sales_tax_status": "TAXABLE",
  "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":"2011-09-14T16:00:41Z",
  "created_at":"2011-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
    }
  }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
  <bill>
    <contact>https://api.freeagent.com/v2/contacts/1</contact>
    <category>https://api.freeagent.com/v2/categories/285</category>
    <reference>sdasd</reference>
    <dated-on type="date">2011-09-14</dated-on>
    <due-on type="date">2011-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">2011-09-14T16:00:41Z</updated-at>
    <created-at type="datetime">2011-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>
</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