Hello everyone 
This is an important message that all API users should read.
We are currently working on updating bills within FreeAgent to handle multiple line items, allowing customers and integrators to add bills to FreeAgent which more closely resemble the supplier invoice they receive. This has been a much requested feature and we are excited to be working on it!
As this will fundamentally change how FreeAgent represents a bill, we are releasing the changes to the bills API over 3 stages detailed below. This is to give integrators time to update their integrations as the final change is unfortunately not backwards compatible.
The new documentation has been released for the new endpoints.
To give existing integrators (integrations created before 19th May 2021) time to update their integrations we have released the new version of the API behind a new feature header in the request. By supplying the header FreeAgent-Feature: bill_items you will be able to retrieve, create and update bills with the new schema.
New integrators (integrations created after 19th May 2021) will only have access to the new schema.
Changes to creating a bill:
In the current schema, an integrator would use this request to create a bill:
curl -v -XPOST "https://api.freeagent.com/v2/bills" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-type: application/json" \
-H "Accept: application/json" \
--data @- << EOH
{
"bill":{
"contact":"https://api.freeagent.com/v2/contacts/27",
"category":"https://api.freeagent.com/v2/categories/289",
"reference":"REF001",
"dated_on":"2021-04-01",
"due_on":"2021-05-01",
"total_value":"100.0",
"sales_tax_rate":"20"
}
}
EOH
For the new schema we need to move some of the attributes to a bill item like this:
curl -v -XPOST "https://api.freeagent.com/v2/bills" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-type: application/json" \
-H "Accept: application/json" \
-H "FreeAgent-Features: bill_items" \
--data @- << EOH
{
"bill":{
"contact":"https://api.freeagent.com/v2/contacts/27",
"reference":"REF001",
"dated_on":"2021-04-01",
"due_on":"2021-05-01",
"bill_items":[
{
"description": "N/A",
"category":"https://api.freeagent.com/v2/categories/289",
"total_value":"100.0",
"sales_tax_rate":"20"
}
]
}
}
EOH
From the request above you can see the new bill_items array has been added and the category, total_value and sales_tax_rate has been moved inside the bill item. Also note the additional FreeAgent-Features header. Without this header the request would be rejected.
Changes to retrieving a bill:
We will be removing several fields from the bill response in the new schema and moving these fields into the “BillItem” object. These fields are:
categorysales_tax_ratesecond_sales_tax_ratesales_tax_statussecond_sales_tax_status-
manual_sales_tax_amount
These values will now be available in thebill_itemskey for each bill.
So, for example, if we requested all bills from /v2/bills, the current schema would look like this:
{ "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":"REF001",
"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",
"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
}
}
]}
When requesting the same endpoint and using the FreeAgent-Features: bill_items header, the response will change to look like this:
{ "bills":[{
"url":"https://api.freeagent.com/v2/bills/1",
"contact":"https://api.freeagent.com/v2/contacts/1",
"reference":"REF001",
"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":"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
},
}
]}
Similar to invoices, we have added a nested_bill_items query parameter if you need to include the bill items in the index response, which will save lots of extra fetching from the API. So if you requested /v2/bills?nested_bill_items=true, the response would look like this:
{ "bills":[{
"url":"https://api.freeagent.com/v2/bills/1",
"contact":"https://api.freeagent.com/v2/contacts/1",
"reference":"REF001",
"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":"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
},
},
"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/1",
"description":"Alex Gregory - Bill REF 001",
"category":"https://api.freeagent.com/v2/categories/285",
"total_value":"213.0",
"sales_tax_status":"TAXABLE",
"second_sales_tax_status":"TAXABLE",
"sales_tax_rate":"20.0",
"sales_tax_value":"-35.5",
}
]
}
]}
When retrieving a single bill the response will always include the bill items.
A full list of bill and bill item attributes can be found in the API documentation.
The Stages of API Changes:
From today:
- For existing integrators the new bill schema is available by adding the
FreeAgent-Feature: bill_itemsheader in the request to the bills API. - New integrators (integrations created after 19th May 2021) will only have access to the new schema via the bills API.
- We will only accept a single line item at this time.
After September 1st:
-
We will no longer guarantee functionality of the old endpoints - these could be switched off at any time after this date.
-
We will still only accept a single line item at this time.
-
Once the old endpoints have been removed, we’ll post to the forum to let you all know and existing integrators can stop sending the FreeAgent-Feature header and we will only accept the new schema.
What’s next on the engineering side
Behind the scenes, we have some engineering work to complete once all our users have switched to our new endpoints to build the multiple line items onto Bills.
Multi-item Bill Feature Release (Q1 2022)
- Restrictions on number of line items will be removed, enabling creation of bills with multiple line items. When this happens, we’ll post to the API forum to let everyone know and there’ll be a pre-release note to let you all know when it is available on our Sandbox environment for testin
If you have any questions or concerns regarding this deprecation, or the new bills endpoints, please do let us know as soon as you can by replying to this post. We’ll be monitoring this thread for any questions or feedback you may have, and will do our best to get back to you as soon as we can.
Also, if you think you’ll need assistance, or specific help ahead of the migration, please do let us know.
All the best,
Anna Whittingham
Engineering Manager at FreeAgent
Posted: 19th May 2021
