Bill Changes and Deprecations, Bills with Multiple Line Items

Hello everyone :wave:

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:

  • category
  • sales_tax_rate
  • second_sales_tax_rate
  • sales_tax_status
  • second_sales_tax_status
  • manual_sales_tax_amount
    These values will now be available in the bill_items key 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_items header 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

1 Like

Hi everyone,

It’s been a month since our announcement of our Bills API deprecation and it’s been great to see that some of you have already begun to switch over to the new endpoints - thank you! :tada:

If you’ve not had a chance to do so yet, we just wanted to remind you that the new endpoints constitute a breaking change that will not be backwards compatible.

There are now two months remaining before we stop guaranteeing the functionality of the old style endpoints.

If you’ve not switched over yet, don’t panic! There’s plenty of time, and the previous post should give you all the guidance that you need. But as ever, if you do have any questions or need specific assistance, do reach out and we’ll do our very best to help.

All the best,
Anna

Hello again everyone,

It’s that time again for me to remind you about our Bills API deprecation and the need to switch over! Thanks to all of you who have switched over already, it’s really appreciated. :tada:

If you’ve not had a chance to do so yet, we just wanted to remind you that the new endpoints constitute a breaking change that will not be backwards compatible.

There is now one month remaining before we stop guaranteeing the functionality of the old style endpoints after August 19th. Once we’ve got everyone on the new endpoints, we’ll be working hard to release the ability to add multiple categories to bills!

If you’ve not switched over yet, don’t panic! There’s still time, and the previous post should give you all the guidance that you need. From our users who have already switched, we’ve not seen any problems, but as ever, if you do have any questions or need specific assistance, do reach out and we’ll do our very best to help.

All the best,
Anna

Hi all!

Just a quick update from our end - we’ve found some hidden complexity in our build which has meant we’ve had to adjust our timescale on completing the deprecation. I’ve updated the original post but here are the summary of changes for clarity.

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 testing.

As ever, if you have any questions, please let us know!

All the best,
Anna

Hi all,

It seems that we still have some users on our old endpoints, so this is the last call to switch over.

We will be turning the endpoints off on October 31st. After this, any old integrations will stop working as the change is not backwards compatible, so if you’ve not had a chance to switch over yet, please prioritise this as soon as possible.

After October 31st:

  • The old endpoints will no longer work.

  • 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 testing.

As ever, if you have any questions or need any support, please do let us know.

All the best,
Anna