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