Customizable Chart of Accounts and API Changes
With the move to our new customizable Chart of Accounts (CoA) comes changes to the structure of accounts, expense categories, and reports. This means how you use the API today will change.
Details
Who is affected?
- Beginning on July 20th, all new trial and paid systems received the new customizable Chart of Accounts structure and functionality. If customers use the new functionality but do not engage with APIs or integrations, their experience will remain intact; otherwise, they may see some incorrect information
- Existing customers will not see any differences to their systems, CoA or how they work—which means the current APIs will work as expected. However, they will eventually be moved over to the new CoA structure.
What is changing?
- New capabilities allow Owners to manage the structure of their CoA, including creating, editing, archiving, and moving both parent and sub-accounts (some exceptions apply)
- As a result, the current APIs for injecting transactions and accounts/expense categories, and pulling data/reports change (see below for details, as well as the end of the document for sample calls)
Overview of API Changes
| API | What is being changed | What can an API user do |
|---|---|---|
| Expense | GET, POST and PUT logic | – Post an expense to an Operating Expense Account – Post an expense to a Cost of Goods Sold (COGS) account. COGS accounts are new. |
| Expense Category | GET, POST and PUT logic | – Post an expense to an Operating Expense Account – Post an expense to a Cost of Goods Sold (COGS) account – The parent_category’s “is_cogs” value must match the category’s “is_cogs” value |
| New Accounts | Full support for CRUD operations and archive/unarchive | – Create an account and specify all fields available in the UI: account type, account sub-type, parent account (new), sub-account, account number, and account description – Edit, archive and unarchive accounts* *Note: some accounts and sub-accounts are not editable via API as they’re required for overall FreshBooks functionality |
| Manual Journal Entry | POST will accept new property “categoryid” for expense category id | Post a manual Journal Entry to any account in the new account service |
API Changes
| FreshBooks Functionality | Call Type | What Will Happen at Beta for New Customers? |
|---|---|---|
| Expenses(↗ additional docs) | GET | You’ll get an updated categoryid that will account for the new structure and whether or not the account/expense category is an Operating Expense (OpEx) or Cost of Goods Sold (COGS) |
| PUT | If you send is_cogs = true and the categoryid passed alongside the request does not have the same cogs value (i.e. the categoryid has an is_cogs value of false), we’ll ignore the is_cogs = true value and assign the expense to the categoryid. Categoryid will take precedence over the is_cogs value in the request. | |
| POST | If you send is_cogs = true and the categoryid passed alongside the request does not have the same cogs value (i.e. the categoryid has an is_cogs value of false), we’ll ignore the is_cogs = true value and assign the expense to the categoryid. Categoryid will take precedence over the is_cogs value in the request. | |
| Expense categories(↗ additional docs) | GET | Similar to expenses, you’ll get an updated categoryid that will account for the new structure and whether or not the account/expense category is an Operating Expense (OpEx) or Cost of Goods Sold (COGS) |
| PUT | – Updating the “is_cogs” value is no longer allowed — results in a 422 – Updating the “parent_categoryid” to a category where the parent “is_cogs” value does not match the category’s “is_cogs” value results in a 422 |
|
| POST | The parent_category’s is_cogs value must match the categories “is_cogs” value | |
| Manual Journal Entries (↗ additional docs) |
POST | Post as normal. Any is_cogs information will be handled on our back-end to update true_is_cogs, categoryid and to spin up new accounts/expense categories as required |
| Reports (↗ additional docs) |
GET | Reports will only display the old versions of reports and will not reflect account sub-types, COGS, and the new parent / sub-account hierarchy |
Sample API responses at Beta
Expenses GET
{
"response": {
"result": {
"expense": {
"account_name": "Plaid Checking",
"accountid": null,
"accounting_systemid": "6Veo",
"amount": {
"amount": "12.00",
"code": "USD"
},
...
"categoryid": 412,
...
"is_cogs": true,
...
"transactionid": 253,
"updated": "2022-06-01 23:04:56",
"vendor": "McDonald's",
"vis_state": 0
}
}
}
}
Expenses PUT
{
"response": {
"result": {
"expense": {
"account_name": "Plaid Checking",
"accountid": null,
"accounting_systemid": "6Veo",
"amount": {
"amount": "12.00",
"code": "USD"
},
...
"categoryid": 412,
"clientid": 0,
...
"is_cogs": true,
...
"transactionid": 253,
"updated": "2022-06-01 23:04:56",
"vendor": "McDonald's",
"vis_state": 0
}
}
}
}
Expenses POST’
{
"response": {
"result": {
"expense": {
"account_name": "Plaid Checking",
"accountid": null,
"accounting_systemid": "6Veo",
"amount": {
"amount": "12.00",
"code": "USD"
},
...
"categoryid": 412,
"clientid": 0,
...
"is_cogs": true,
...
"transactionid": 253,
"updated": "2022-06-01 23:04:56",
"vendor": "McDonald's",
"vis_state": 0
}
}
}
}—————————————————————————-
Expense Categories GET
{
"response": {
"result": {
"category": {
"category": "Advertising",
"categoryid": 93992990,
"id": 93992990,
"is_editable": false,
"is_cogs": false,
"parentid": 121904083,
"vis_state": 0
}
}
}
}
Expense Categories PUT
| 422 |
Expense Categories POST
{
"response": {
"result": {
"category": {
"category": "MyTestCategory",
"categoryid": 6621137,
"created_at": "2022-06-09 13:58:09",
"id": 6621137,
"is_cogs": false,
"is_editable": true,
"parentid": 3508622,
"transaction_posted": false,
"updated_at": "2022-06-09 13:58:09",
"vis_state": 0
}
}
}
}—————————————————————————-
Manual Journal Entries GET
{
"response": {
"result": {
"journal_entry": {
"currency_code": "USD",
"description": "Here is a basic description of the journal entry made.",
"details": [
{
"categoryid": 251,
"credit": null,
"currency_code": "USD",
"debit": "200",
"description": "Here is a basic description of the journal entry made.",
"detailid": 205,
"id": 205,
"name": "JournalEntry",
"sub_accountid": 167,
"user_entered_date": "2019-04-20"
},
{
"categoryid": null,
"credit": "200",
"currency_code": "USD",
"debit": null,
"description": "Here is a basic description of the journal entry made.",
"detailid": 206,
"id": 206,
"name": "JournalEntry",
"sub_accountid": 106,
"user_entered_date": "2019-04-20"
}
],
"entryid": 103,
"id": 103,
"name": "JournalEntry",
"user_entered_date": "2019-04-20"
}
}
}
}Manual Journal Entries PUT
{
"response": {
"result": {
"journal_entry": {
"currency_code": "USD",
"description": "Here is a basic description of the journal entry made.",
"details": [
{
"categoryid": 251,
"credit": null,
"currency_code": "USD",
"debit": "200",
"description": "Here is a basic description of the journal entry made.",
"detailid": 205,
"id": 205,
"name": "JournalEntry",
"sub_accountid": 167,
"user_entered_date": "2019-04-20"
},
{
"categoryid": null,
"credit": "200",
"currency_code": "USD",
"debit": null,
"description": "Here is a basic description of the journal entry made.",
"detailid": 206,
"id": 206,
"name": "JournalEntry",
"sub_accountid": 106,
"user_entered_date": "2019-04-20"
}
],
"entryid": 103,
"id": 103,
"name": "JournalEntry",
"user_entered_date": "2019-04-20"
}
}
}
}—————————————————————————-
Reports GET (same as today)
{
"response": {
"result": {
"general_ledger": {
"company_name": "Flex CoA Beta Test",
"currency_code": "CAD",
"data": [
{
"account_name": "Cash",
"account_number": "1000",
"accountid": 4249771,
...
"sub_accounts": [
{
"categoryid": null,
...
"sub_account_name": "Petty Cash",
"sub_account_number": "1",
"sub_accountid": 5504506,
"transactions": [
...
]
}
]
},
{
"account_name": "Operating Expenses",
"account_number": "6000",
"accountid": 4249784,
...
"sub_accounts": [
{
"categoryid": null,
...
"sub_account_name": "Uncategorized Expenses",
"sub_account_number": "1",
"sub_accountid": 5505249,
"transactions": [
...
]
},
{
"categoryid": null,
...
"sub_account_name": "Rent or Lease",
"sub_account_number": "12",
"sub_accountid": 5505266,
"transactions": [
...
]
},
...
]
}
],
"download_token": <token>,
"end_date": "2022-06-30",
"start_date": "2022-06-01",
"summary": {
"total_credit": {
"amount": "6223.00",
"code": "CAD"
},
"total_debit": {
"amount": "6223.00",
"code": "CAD"
}
},
"summary_only": false
}
}
}
}