Hi everyone 
This is an important message that all API users should read.
We are currently in the process of expanding our support for different methods of depreciation for capital assets. Currently, FreeAgent supports straight-line depreciation of 2-7 years, with depreciation applied once a year on the anniversary of the date of purchase. We know that this isn’t always suitable for all capital asset purchases, so we will be adding the support for assets with no depreciation or on the reducing balance method. We will also be increasing the maximum asset life from 7 to 25 years on the straight-line depreciation method. Additionally, we will allow depreciation to be applied monthly, instead of just annually, to give FreeAgent users a more accurate picture of their financial situation throughout the year.
As we make these changes to FreeAgent, we will also need to update the API. This will affect all API users who interact with Capital Assets, Bank Account Entries, Bill Items or Expenses, and does require you to take action to ensure that your application continues to work as expected. If you do not have any capital assets, these changes will not affect you.
What’s changing?
- Bill Items and Expenses
- Currently, bill items and expenses that reference the purchase of a capital asset contain the field
depreciation_schedule. This field will be deprecated, and eventually removed later in 2024. Please also note that once the new depreciation methods are available, and until the removal of this field, this will be set to 0 for assets with no depreciation. - When the item refers to the purchase of a capital asset, we will be including a
capital_assetfield, which will contain a link to the purchased asset. Further information about the asset’s depreciation method and schedule can be found by accessing the associated capital asset. - Until the removal of the deprecated field later in 2024, we will still support the updating of expenses and bill items with the deprecated field, but only if the asset is already on the legacy annual, straight line depreciation method. To update an expense or a bill item associated with a capital asset that is on any new depreciation method or frequency, the new
depreciation_profilemust be used once it is supported (read more about when this will happen in the next section). - Until the removal of the deprecated field later in 2024, we will still support the creation of expenses and bill items with the deprecated field, with the associated capital asset being set to the legacy annual, straight line depreciation method. Note that the deprecated field will also still have the previous limitation of 2-7 years asset life.
- If the new
depreciation_profileisn’t used in the necessary cases, we will send back a 422 Unprocessable Entity response status.
- Currently, bill items and expenses that reference the purchase of a capital asset contain the field
Example responses
GET https://api.freeagent.com/v2/bills/:id
{
"bill": {
"url": "http://api.lvh.me:3000/v2/bills/5",
"contact": "http://api.lvh.me:3000/v2/contacts/1",
"reference": "HELLO",
"dated_on": "2023-11-13",
"due_on": "2023-12-13",
"total_value": "3000.0",
"net_value": "-2500.0",
"paid_value": "0.0",
"due_value": "3000.0",
"native_due_value": "3000.0",
"input_total_values_inc_tax": true,
"currency": "GBP",
"sales_tax_value": "-500.0",
"status": "Open",
"long_status": "Open - due in about 1 month",
"updated_at": "2023-11-13T09:40:53.000Z",
"created_at": "2023-11-13T09:40:53.000Z",
"contact_name": "Test Contact",
"bill_items": [
{
"url": "http://api.lvh.me:3000/v2/bill_items/6",
"bill": "http://api.lvh.me:3000/v2/bills/5",
"description": "Computer",
"capital_asset": "https://api.freeagent.com/v2/capital_assets/3"
"category": "http://api.lvh.me:3000/v2/categories/602-1",
"total_value": "3000.0",
"total_value_ex_tax": "2500.0",
"sales_tax_status": "TAXABLE",
"sales_tax_rate": "20.0",
"sales_tax_value": "-500.0"
}
],
"is_paid_by_hire_purchase": false
}
}
POST https://api.freeagent.com/v2/bills
{
"bill": {
"contact": "https://api.freeagent.com/v2/contacts/1",
"reference": "REF100",
"dated_on": "2020-09-14",
"due_on": "2020-10-14",
"bill_items": [
{
"capital_asset": {
"depreciation_profile": {
"method": "reducing_balance",
"annual_depreciation_percentage": 20,
"frequency": "annual"
}
},
"category": "https://api.freeagent.com/v2/categories/602-4",
"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"
}
]
}
}
GET https://api.freeagent.com/v2/expenses/:id
{
"expense": {
"url": "http://api.lvh.me:3000/v2/expenses/23",
"user": "http://api.lvh.me:3000/v2/users/120",
"capital_asset": "https://api.freeagent.com/v2/capital_assets/2",
"category": "http://api.lvh.me:3000/v2/categories/602-4",
"dated_on": "2023-07-23",
"currency": "GBP",
"gross_value": "-8000.0",
"native_gross_value": "-8000.0",
"sales_tax_rate": "20.0",
"sales_tax_value": "-1333.33",
"native_sales_tax_value": "-1333.33",
"sales_tax_status": "TAXABLE",
"description": "Purchase of camera equipment",
"updated_at": "2023-11-13T09:50:45.000Z",
"created_at": "2023-11-13T09:50:45.000Z"
}
}
POST https://api.freeagent.com/v2/expenses
{
"expense": {
"user": "http://api.lvh.me:3000/v2/users/120",
"capital_asset": {
"depreciation_profile": {
"asset_life_years": 3,
"method": "straight_line",
"frequency": "annual"
}
},
"category": "http://api.lvh.me:3000/v2/categories/602-4",
"dated_on": "2023-07-23",
"gross_value": "-8000.0",
"description": "Purchase of camera equipment"
}
}
-
- Currently, bank transaction explanations that reference the purchase of a capital asset contain the field
asset_life_years. This field will be deprecated, and eventually removed later in 2024. You will be able to access this information through the associated capital asset, using the existingcapital_assetfield to get its URL. Please also note that once the new depreciation methods are available, and until the removal of this field, this will be set to 0 for assets with no depreciation. - Until the removal of the deprecated field later in 2024, we will still support the updating of bank transaction explanations with the deprecated field, but only if the asset is already on the legacy annual, straight line depreciation method. To update a bank transaction explanation associated with a capital asset that is on any new depreciation method or frequency, the new
depreciation_profilemust be used once it is supported (read more about when this will happen in the next section). - Until the removal of the deprecated field later in 2024, we will still support the creation of bank transaction explanations with the deprecated field, with the associated capital asset being set to the legacy annual, straight line depreciation method. Note that the deprecated field will also still have the previous limitation of 2-7 years asset life.
- If the new
depreciation_profileisn’t used in the necessary cases, we will send back a 422 Unprocessable Entity response status.
- Currently, bank transaction explanations that reference the purchase of a capital asset contain the field
-
- Currently, capital assets contain the field
asset_life_years. This field will be deprecated, and eventually removed later in 2024, as it is not sufficient to cover the new methods of depreciation that will be introduced. Please also note that once the new depreciation methods are available, and until the removal of this field, this will be set to 0 for assets with no depreciation. - We will be adding a
depreciation_profilefield to capital assets, which will contain information about the method of depreciation (legacy straight line, straight line, reducing balance or no depreciation), asset life (for straight line methods only), annual depreciation percentage (for reducing balance method only) and frequency of depreciation (monthly or annually, present for both straight line and reducing balance methods, but absent for no depreciation). When viewing the capital asset entity for a source item that uses the legacy straight line depreciation method, the method will be set tolegacy_straight_line.
- Currently, capital assets contain the field
Example responses
GET https://api.freeagent.com/v2/capital_assets/:id
{
"capital_asset": {
"url": "https://api.freeagent.com/v2/capital_assets/3",
"depreciation_profile": {
"asset_life_years": 10,
"method": "straight_line",
"frequency": "annual"
},
"description": "Workstation",
"asset_type": "Computer Equipment Purchase",
"purchased_on": "2014-10-07",
"disposed_on": "2015-12-07",
"created_at": "2014-10-07T10:41:21.000Z",
"updated_at": "2014-10-07T10:41:43.000Z"
}
}
{
"capital_asset": {
"url": "https://api.freeagent.com/v2/capital_assets/3",
"depreciation_profile": {
"annual_depreciation_percentage": 20,
"method": "reducing_balance",
"frequency": "annual"
},
"description": "Workstation",
"asset_type": "Computer Equipment Purchase",
"purchased_on": "2014-10-07",
"disposed_on": "2015-12-07",
"created_at": "2014-10-07T10:41:21.000Z",
"updated_at": "2014-10-07T10:41:43.000Z"
}
}
{
"capital_asset": {
"url": "https://api.freeagent.com/v2/capital_assets/3",
"depreciation_profile": {
"method": "no_depreciation"
},
"description": "Workstation",
"asset_type": "Computer Equipment Purchase",
"purchased_on": "2014-10-07",
"disposed_on": "2015-12-07",
"created_at": "2014-10-07T10:41:21.000Z",
"updated_at": "2014-10-07T10:41:43.000Z"
}
}
When is this happening?
This change will not happen before early 2024. We’ll post a reminder closer to the time. You can also view the most recent changes in our API change log. We recommend that you switch over to using the new fields as soon as possible after the release. Even though the deprecated fields will still exist for a short time after the release, we will remove them entirely later in 2024.
If you have any questions about these changes or notice any issues after this has been implemented, please post on the forum where a member of the community or a FreeAgent staff member may be able to help you.