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 3 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 a 3 month deprecation period:

  • The old schema will be removed from the API and we will only accept the new schema for all integrators.
  • Existing integrators can stop sending the FreeAgent-Feature header. The header will now be ignored.
  • We will still only accept a single line item at this time.

Once the feature is complete and has been fully released:

  • Restrictions on number of line items will be removed, enabling creation of bills with multiple line items.
  • We expect to release this feature towards the end of this year.

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 and out and we’ll do our very best to help.

All the best,
Anna