Skip to content
× FreshBooks App Logo
FreshBooks
Official App
Free - Google Play
Get it
You're currently on our US site. Select your regional site here:

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

APIWhat is being changedWhat 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
            }
        }
    }
}