Bills

Minimum access level: Bills, unless stated otherwise.

Currently bills can only contain a single bill_item on the production API; however, support for multiple bill items is available in advance to API integrators for testing on the FreeAgent Sandbox. Read the API Forum announcement for more details.

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
	due_value	Due value of the bill	Decimal
	native_due_value	Due value of the bill in the company's native currency, calculated using the exchange rate on the bill's `paid_on` date if the bill is fully paid or a bill refund; Otherwise, today's `exchange_rate` is used instead	Decimal
	net_value	Net value of the bill	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, up to a maximum of 40. 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	Identifier of the bill item to update/delete, or blank to create a new bill item. Optional when creating bills, required when updating.	URI
	bill	The parent bill of the item	URI
✔	category	Accounting category of the bill item	URI
?	description	Description of the bill item Required when `category` is of capital asset type Not relevant when `unit` is `Stock`.	String
✔	total_value	Value of the item including taxes	Decimal
	total_value_ex_tax	Value of the item excluding taxes, may be used instead of `total_value`	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	One of the following: `-no unit-` (default) `Hours` `Days` `Weeks` `Months` `Years` `Products` `Services` `Training` `Stock`	String
	quantity	Quantity of the `unit` Present when `category` is not of capital asset type or Purchase of Stock Presently this will be defaulted to `1`	Decimal
?	stock_item	Stock item being purchased, required when category is set to Stock	URI
	stock_item_description	Description of the bill item's stock item, only returned when stock item is set	String
?	stock_altering_quantity	Quantity of `stock_item` units purchased, required when category is set to Stock	Decimal
	depreciation_schedule	The depreciation schedule of the item
	project	The project being billed	URI
Additional attributes when updating a bill item
✔	url	URL to identify the bill item to update	URI
Additional attributes when deleting a bill item
✔	url	URL to identify the bill item to delete	URI
✔	_destroy	Should be equal to `1`	Integer

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.
open_or_overdue_payments: Show only open or overdue bill payments (bills with positive total value).
open_or_overdue_refunds: Show only open or overdue bill refunds (bills with negative total value).
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",
  "net_value":"-177.5",
  "exchange_rate":"0.09702361",
  "paid_value":"200.0",
  "due_value":"13.0",
  "native_due_value":"1.27",
  "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>
      <net-value type="decimal">-177.5</net-value>
      <exchange-rate type="decimal">0.09702361</exchange-rate>
      <paid-value type="decimal">200.0</paid-value>
      <due-value type="decimal">13.0</due-value>
      <native-due-value type="decimal">1.27</native-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",
  "net_value":"-177.5",
  "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/1",
        "bill":"https://api.freeagent.com/v2/bills/1",
        "description":"Alex Gregory - Bill REF 001",
        "category":"https://api.freeagent.com/v2/categories/609-1",
        "quantity":"1.0",
        "unit":"Stock",
        "total_value":"213.0",
        "total_value_ex_tax":"177.5",
        "sales_tax_status":"TAXABLE",
        "second_sales_tax_status":"TAXABLE",
        "sales_tax_rate":"20.0",
        "sales_tax_value":"-35.5",
        "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>
      <net-value type="decimal">-177.5</net-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>
          <url>https://api.freeagent.com/v2/bill_items/1</url>
          <bill>https://api.freeagent.com/v2/bills/1</bill>
          <category>https://api.freeagent.com/v2/categories/609-1</category>
          <description>Alex Gregory - Bill REF100</description>
          <quantity type="decimal">1.0</quantity>
          <sales-tax-rate type="decimal">20.0</sales-tax-rate>
          <sales-tax-status>TAXABLE</sales-tax-status>
          <sales-tax-value type="decimal">-35.5</sales-tax-value>
          <second-sales-tax-rate type="decimal">0.0</second-sales-tax-rate>
          <second-sales-tax-status>TAXABLE</second-sales-tax-status>
          <second-sales-tax-value type="decimal">0.0</second-sales-tax-value>
          <stock-item>https://api.freeagent.com/v2/stock_item/42</stock-item>
          <total-value type="decimal">213.0</total-value>
          <total-value-ex-tax type="decimal">177.5</total-value-ex-tax>
          <unit>Stock</unit>
        </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",
  "net_value":"-83.33",
  "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/1",
        "bill":"https://api.freeagent.com/v2/bills/1",
        "description":"Alex Gregory - Bill REF100",
        "category":"https://api.freeagent.com/v2/categories/609-1",
        "quantity":"1.0",
        "unit":"Stock",
        "total_value":"100.0",
        "total_value_ex_tax":"83.33",
        "sales_tax_status":"TAXABLE",
        "second_sales_tax_status":"TAXABLE",
        "sales_tax_rate":"20.0",
        "sales_tax_value":"-16.67",
        "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>
    <net-value type="decimal">-83.33</net-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>
        <url>https://api.freeagent.com/v2/bill_items/1</url>
        <bill>https://api.freeagent.com/v2/bills/1</bill>
        <category>https://api.freeagent.com/v2/categories/609-1</category>
        <description>Alex Gregory - Bill REF100</description>
        <quantity type="decimal">1.0</quantity>
        <sales-tax-rate type="decimal">20.0</sales-tax-rate>
        <sales-tax-status>TAXABLE</sales-tax-status>
        <sales-tax-value type="decimal">-16.67</sales-tax-value>
        <second-sales-tax-rate type="decimal">0.0</second-sales-tax-rate>
        <second-sales-tax-status>TAXABLE</second-sales-tax-status>
        <second-sales-tax-value type="decimal">0.0</second-sales-tax-value>
        <stock-item>https://api.freeagent.com/v2/stock_item/42</stock-item>
        <total-value type="decimal">100.0</total-value>
        <total-value-ex-tax type="decimal">83.33</total-value-ex-tax>
        <unit>Stock</unit>
      </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 must have a root bill element, containing elements listed under Attributes.

Example Request Body

{
  "bill": {
    "contact": "https://api.freeagent.com/v2/contacts/1",
    "reference": "REF100",
    "dated_on": "2020-09-14",
    "due_on": "2020-10-14",
    "bill_items": [
      {
        "category": "https://api.freeagent.com/v2/categories/609",
        "description": "Alex Gregory - Bill REF100",
        "sales_tax_rate": "20.0",
        "stock_altering_quantity": "1.0",
        "stock_item": "https://api.freeagent.com/v2/stock_item/42",
        "total_value": "100.0"
      }
    ]
  }
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<bill>
  <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>
  <bill-items type="array">
    <bill-item>
      <category>https://api.freeagent.com/v2/categories/609</category>
      <description>Alex Gregory - Bill REF100</description>
      <sales-tax-rate type="decimal">20.0</sales-tax-rate>
      <stock-altering-quantity type="decimal">1.0</stock-altering-quantity>
      <stock-item>https://api.freeagent.com/v2/stock_item/42</stock-item>
      <total-value type="decimal">100.0</total-value>
    </bill-item>
  </bill-items>
</bill>

Show as JSON

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",
  "net_value":"83.33",
  "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/1",
        "bill":"https://api.freeagent.com/v2/bills/1",
        "description":"Alex Gregory - Bill REF100",
        "category":"https://api.freeagent.com/v2/categories/609-1",
        "quantity":"1.0",
        "unit":"Stock",
        "total_value":"100.0",
        "total_value_ex_tax":"83.33",
        "sales_tax_status":"TAXABLE",
        "second_sales_tax_status":"TAXABLE",
        "sales_tax_rate":"20.0",
        "sales_tax_value":"-16.67",
        "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>
    <net-value type="decimal">83.33</net-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>
        <url>https://api.freeagent.com/v2/bill_items/1</url>
        <bill>https://api.freeagent.com/v2/bills/1</bill>
        <category>https://api.freeagent.com/v2/categories/609-1</category>
        <description>Alex Gregory - Bill REF100</description>
        <quantity type="decimal">1.0</quantity>
        <sales-tax-rate type="decimal">20.0</sales-tax-rate>
        <sales-tax-status>TAXABLE</sales-tax-status>
        <sales-tax-value type="decimal">-16.67</sales-tax-value>
        <second-sales-tax-rate type="decimal">0.0</second-sales-tax-rate>
        <second-sales-tax-status>TAXABLE</second-sales-tax-status>
        <second-sales-tax-value type="decimal">0.0</second_sales-tax-value>
        <stock-item>https://api.freeagent.com/v2/stock_item/42</stock-item>
        <total-value type="decimal">100.0</total-value>
        <total-value-ex-tax type="decimal">83.33</total-value-ex-tax>
        <unit>Stock</unit>
      </bill-item>
    </bill-items>
  </bill>
</freeagent>

Show as JSON

Update a bill

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

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

Bill items must have a url attribute, either set to the URL identifier of an existing bill item to update or delete or to an empty string to create a new bill item.

Bills are currently limited to one bill item, however API integrations are expected to supply the url attribute of the single bill item when updating bills. This ensures it will work correctly in future when there are varying numbers of bill items.

Example Single Item Request Body

This example updates the bill's reference and updates the description & total value on the bill item.

{
  "bill": {
    "reference": "REF100",
    "bill_items": [
      {
        "url": "https://api.freeagent.com/v2/bill_items/100001",
        "description": "Updating an existing bill item",
        "total_value": "172.50"
      }
    ]
  }
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<bill>
  <reference>REF100</reference>
  <bill-items type="array">
    <bill-item>
      <url>https://api.freeagent.com/v2/bill_items/100001</url>
      <description>Updating an existing bill item</description>
      <total-value type="decimal">172.50</total-value>
    </bill-item>
  </bill-items>
</bill>

Show as JSON

Example Multi-Item Request Body

This is an example of future functionality when multiple bill items are supported.

This example updates the bill's reference, updates the description & total value on one bill item, deletes a second bill item and creates a third bill item.

{
  "bill": {
    "reference": "REF100",
    "bill_items": [
      {
        "url": "https://api.freeagent.com/v2/bill_items/100001",
        "description": "Updating an existing bill item",
        "total_value": "172.50"
      },
      {
        "url": "https://api.freeagent.com/v2/bill_items/200002",
        "_destroy": 1
      },
      {
        "url": "",
        "category": "https://api.freeagent.com/v2/categories/285",
        "description": "New bill item for accommodation fees",
        "total_value": "200.00"
      }
    ]
  }
}

Show as XML

<?xml version="1.0" encoding="UTF-8"?>
<bill>
  <reference>REF100</reference>
  <bill-items type="array">
    <bill-item>
      <url>https://api.freeagent.com/v2/bill_items/100001</url>
      <description>Updating an existing bill item</description>
      <total-value type="decimal">172.50</total-value>
    </bill-item>
    <bill-item>
      <url>https://api.freeagent.com/v2/bill_items/200002</url>
      <_destroy type="integer">1</_destroy>
    </bill-item>
    <bill-item>
      <url></url>
      <category>https://api.freeagent.com/v2/categories/285</category>
      <description>New bill item for accommodation fees</description>
      <total-value type="decimal">200.0</total-value>
    </bill-item>
  </bill-items>
</bill>

Show as JSON

Response

Status: 200 OK

Delete a bill

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

Response

Status: 200 OK

Bills

Attributes

Bill Item Attributes

List all bills

Input

View Filters

Date Filters

Response

List all bills with nested bill items

Response

Get a single bill

Response

List all bills related to a contact

List all bills related to a project

Create a bill

Example Request Body

Response

Update a bill

Example Single Item Request Body

Example Multi-Item Request Body

Response

Delete a bill

Response