Expenses

Expenses are used to track expenditures your business incurs. To attach uploaded receipts to an expense, see Expense Attachments.

Access Requirements

Access	Requires Authorization
Scopes	`user:expenses:read` `user:expenses:write`

Expense Status Table

Expense statuses are not directly modifiable. Each is a description of the status of the expense, e.g. “expense has client, expense is attached to an invoice”.

code	name	description
0	internal	-internal- rather than client
1	outstanding	has client, needs to be applied to an invoice
2	invoiced	has client, attached to an invoice
4	recouped	has client, attached to an invoice, and paid

Includes

Include Name	Description
attachment	Includes attachment details assocatied with expense receipts
category	Include expense category in expense
expense_profile	Include expense profile info in expense
project	Include related projects in expense
account	Include account info in expense

Filters

Filter Type	Name	Field	Description
Equals	expenseid	expenseid	matches exact expenseid
In	expenseids	expenseid	matches list of expenseids, one specified per query arg
Equals	clientid	clientid	matches exact clientid
In	clientids	clientid	matches list of clientids, one specified per query arg
NotEquals	clientid_not	clientid	any clientid but the parameter
Equals	staffid	staffid	matches exact staffid
In	staffids	staffid	matches list of staffids, one specified per query arg
Equals	profileid	profileid	matches exact profileid
In	profileids	profileid	matches list of profileids, one specified per query arg
Equals	categoryid	categoryid	matches exact categoryid
In	categoryids	categoryid	matches list of categoryids, one specified per query arg
Equals	projectid	projectid	matches exact projectid
In	projectids	projectid	matches list of projectids, one specified per query arg
Equals	has_receipt	has_receipt	true/false expense has related receipt
Between	amount_min	amount	amount greater than or equal to parameter
Between	amount_max	amount	amount less than parameter
Between	date_min	date	date greater than or equal to parameter, YYYY-MM-DD format
Between	date_max	date	date less than parameter, YYYY-MM-DD format
Between	updated_min	updated	updated date greater than or equal to parameter, YYYY-MM-DD format
Between	updated_max	updated	updated date less than parameter, YYYY-MM-DD format
Like	vendor	vendor	vendors containing the parameter
Equals	vendor_eq	vendor	exact match of vendor field
Like	notes	notes	notes containing the parameter
Like	category _name	category	category containing the parameter
Bool	is_cogs	is_cogs	is cost of goods sold or not
In	transactionids	transactionid	matches list of transactionids, one specified per query arg
Equals	accountid	accountid	exact match of accountid
In	accountids	accountid	matches list of accountids, one specified per query arg
Equals	account _name	name	matches exact name
Equal	category _parentid	special	matches either exact categoryid or parentid

Field Descriptions

underlined fields are required on creation

Field	Type	Description
categoryid	int	id of related expense category
markup_percent	string	string-decimal, note of percent to mark expense up
projectid	int	id of related project if applicable
clientid	int	id of related client if applicable
taxPercent1	string	string-decimal tax amount – indicates the maximum tax percentage for this expense, this does not add tax to the expense, instead use taxAmount1
taxName1	string	name of first tax
taxPercent2	string	string-decimal tax amount for second tax – indicates the maximum tax percentage for this expense, this does not add tax to the expense, instead use taxAmount2
taxName2	string	name of second tax
isduplicate	bool	true/false is duplicated expense
profileid	int	id of related profile if applicable
account_name	string	name of related account if applicable
transactionid	int	id of related transaction if applicable
invoiceid	int	id of related invoice if applicable
id	int	duplicate of expenseid
taxAmount1	object	The total for first tax applied to the subtotal amount of the expense
– amount	string	string-decimal amount
– code	string	3-letter currency code
taxAmount2	object	The total for second tax applied to the subtotal amount of the expense
– amount	string	string-decimal amount
– code	string	3-letter currency code}
vis_state	int	0 for active, 1 for deleted
status	int	values from expense status table
bank_name	string	name of bank expense was imported from, if applicable
updated	datetime	time invoice last updated at, YYYY-MM-DD HH:MM:SS format
vendor	string	name of vendor
ext_systemid	int	id of related contractor system if applicable
staffid	int	id of related staff member if applicable
date	date	date of expense, YYYY-MM-DD format
has_receipt	bool	true/false has receipt attached
accounting _systemid	string	unique id for system
background_jobid	int	(internal) id for related background job if applicable
notes	string	notes about expense
ext_invoiceid	int	id of related contractor invoice if applicable
amount	object	Total amount of the expense
– amount	string	string-decimal amount of the expense
– code	string	3-letter currency code
expenseid	int	unique to this business id for expense
compounded_tax	bool	Deprecated. true/false tax2 was a compound tax
accountid	int	id of expense account if applicable

Get Expense

Request: GET https://api.freshbooks.com/accounting/account//expenses/expenses/

Response:

{
  "response": {
    "result": {
      "expense": {
        "categoryid": 121374834,
        "markup_percent": "0",
        "projectid": 0,
        "clientid": 0,
        "taxPercent1": "100",
        "taxName2": null,
        "taxName1": "HST",
        "isduplicate": false,
        "profileid": null,
        "taxPercent2": null,
        "account_name": null,
        "transactionid": null,
        "invoiceid": null,
        "id": 1569533,
        "taxAmount2": null,
        "taxAmount1": {
          "amount": "1.30",
          "code": "CAD"
        },
        "vis_state": 0,
        "status": 0,
        "bank_name": null,
        "updated": "2016-09-27 21:09:13",
        "vendor": "Ice Cream",
        "ext_systemid": 0,
        "staffid": 1,
        "date": "2016-09-19",
        "has_receipt": false,
        "accounting_systemid": "KAG77",
        "background_jobid": null,
        "notes": "Rocky Road",
        "ext_invoiceid": 0,
        "amount": {
          "amount": "10.00",
          "code": "CAD"
        },
        "expenseid": 1569533,
        "compounded_tax": false,
        "accountid": null
      }
    }
  }
}

Create Expense

Request: POST https://api.freshbooks.com/accounting/account//expenses/expenses

{
  "expense": {
    "amount": {
      "amount": "39.991"
    },
    "categoryid": 93993004,
    "staffid": 1,
    "date": "2009-11-24"
  }
}

Response:

{
  "response": {
    "result": {
      "expense": {
        "account_name": null,
        "accountid": null
        "accounting_systemid": "zDmNq",
        "amount": {
          "amount": "39.991",
          "code": "USD"
        },
        "bank_name": null,
        "categoryid": 93993004,
        "clientid": 0,
        "compounded_tax": false,
        "date": "2009-11-24",
        "expenseid": 1574917,
        "ext_invoiceid": 0,
        "ext_systemid": 0,
        "has_receipt": false,
        "id": 1574917,
        "invoiceid": null,
        "isduplicate": true,
        "markup_percent": "0",
        "notes": "",
        "profileid": null,
        "projectid": 0,
        "staffid": 1,
        "status": 0,
        "taxAmount1": null,
        "taxAmount2": null,
        "taxName1": null,
        "taxName2": null,
        "taxPercent1": null,
        "taxPercent2": null,
        "transactionid": null,
        "updated": "2016-09-29 19:08:17",
        "vendor": null,
        "vis_state": 0,
      }
    }
  }
}

Update Single Expense

Request: PUT https://api.freshbooks.com/accounting/account//expenses/expenses/

{
  "expense": {
    "vendor": "Arnold Vendor"
  }
}

Response:

{
  "response": {
    "result": {
      "expense": {
        "categoryid": 93993004,
        "markup_percent": "0",
        "projectid": 0,
        "clientid": 0,
        "taxPercent1": null,
        "taxName2": null,
        "taxName1": null,
        "isduplicate": true,
        "profileid": null,
        "taxPercent2": null,
        "account_name": null,
        "transactionid": null,
        "invoiceid": null,
        "id": 1574917,
        "taxAmount2": null,
        "taxAmount1": null,
        "vis_state": 0,
        "status": 0,
        "bank_name": null,
        "updated": "2016-09-29 19:08:17",
        "vendor": "Arnold Vendor",
        "ext_systemid": 0,
        "staffid": 1,
        "date": "2009-11-24",
        "has_receipt": false,
        "accounting_systemid": "zDmNq",
        "background_jobid": null,
        "notes": "",
        "ext_invoiceid": 0,
        "amount": {
          "amount": "39.991",
          "code": "USD"
        },
        "expenseid": 1574917,
        "compounded_tax": false,
        "accountid": null
      }
    }
  }
}

Delete Single Expense

Request: PUT https://api.freshbooks.com/accounting/account//expenses/expenses/

{
  "expense": {
    "vis_state": 1
  }
}

Response:

{
  "response": {}
}

List Expenses

Request: GET https://api.freshbooks.com/accounting/account//expenses/expenses

Response:

{
  "response": {
    "result": {
      "per_page": 15,
      "pages": 1,
      "total": 3,
      "page": 1,
      "expenses": [
        {
          // same format as single expense
        },
        {
          // same format as single expense
        },
        {
          // same format as single expense
        }
      ]
    }
  }
}

Get Expense

Request: GET

https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>


url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
jsonData = res.json()

Response:


{
 "response": {
   "result": {
     "expense": {
       "categoryid": 121374834,
       "markup_percent": "0",
       "projectid": 0,
       "clientid": 0,
       "taxPercent1": "100",
       "taxName2": null,
       "taxName1": "HST",
       "isduplicate": false,
       "profileid": null,
       "taxPercent2": null,
       "account_name": null,
       "transactionid": null,
       "invoiceid": null,
       "id": 1569533,
       "taxAmount2": null,
       "taxAmount1": {
         "amount": "1.30",
         "code": "CAD"
       },
       "vis_state": 0,
       "status": 0,
       "bank_name": null,
       "updated": "2016-09-27 21:09:13",
       "vendor": "Ice Cream",
       "ext_systemid": 0,
       "staffid": 1,
       "date": "2016-09-19",
       "has_receipt": false,
       "accounting_systemid": "KAG77",
       "background_jobid": null,
       "notes": "Rocky Road",
       "ext_invoiceid": 0,
       "amount": {
         "amount": "10.00",
         "code": "CAD"
       },
       "expenseid": 1569533,
       "compounded_tax": false,
       "accountid": null
      }
    }
  }
}

Create Expense

Request: POST

https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses


url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'expense': {
    'amount': {
      'amount': "39.991"
    },
    'categoryid': 93993004,
    'staffid': 1,
    'date': "2009-11-24"
  }
}
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response:


 {
  "response": {
    "result": {
      "expense": {
        "categoryid": 93993004,
        "markup_percent": "0",
        "projectid": 0,
        "clientid": 0,
        "taxPercent1": null,
        "taxName2": null,
        "taxName1": null,
        "isduplicate": true,
        "profileid": null,
        "taxPercent2": null,
        "account_name": null,
        "transactionid": null,
        "invoiceid": null,
        "id": 1574917,
        "taxAmount2": null,
        "taxAmount1": null,
        "vis_state": 0,
        "status": 0,
        "bank_name": null,
        "updated": "2016-09-29 19:08:17",
        "vendor": null,
        "ext_systemid": 0,
        "staffid": 1,
        "date": "2009-11-24",
        "has_receipt": false,
        "accounting_systemid": "zDmNq",
        "background_jobid": null,
        "notes": "",
        "ext_invoiceid": 0,
        "amount": {
          "amount": "39.991",
          "code": "USD"
        },
        "expenseid": 1574917,
        "compounded_tax": false,
        "accountid": null
      }
    }
  }
}

Update Single Expense

Request: PUT

https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>


url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'expense': {
  'vendor': "Arnold Vendor"
  }
}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Response:


{
  "response": {
    "result": {
      "expense": {
        "categoryid": 93993004,
        "markup_percent": "0",
        "projectid": 0,
        "clientid": 0,
        "taxPercent1": null,
        "taxName2": null,
        "taxName1": null,
        "isduplicate": true,
        "profileid": null,
        "taxPercent2": null,
        "account_name": null,
        "transactionid": null,
        "invoiceid": null,
        "id": 1574917,
        "taxAmount2": null,
        "taxAmount1": null,
        "vis_state": 0,
        "status": 0,
        "bank_name": null,
        "updated": "2016-09-29 19:08:17",
        "vendor": "Arnold Vendor",
        "ext_systemid": 0,
        "staffid": 1,
        "date": "2009-11-24",
        "has_receipt": false,
        "accounting_systemid": "zDmNq",
        "background_jobid": null,
        "notes": "",
        "ext_invoiceid": 0,
        "amount": {
          "amount": "39.991",
          "code": "USD"
        },
        "expenseid": 1574917,
        "compounded_tax": false,
        "accountid": null
      }
    }
  }
}

Delete Single Expense

Request: PUT

https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>


url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<id>"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
payload = {'expense': {
 'vis_state': 1
   }
 }
 res = requests.put(url, data=json.dumps(payload), headers=headers)

Response:


 {
   "response": {}
 }

List Expenses

Request: GET

https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses


url = "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses"
headers = {'Authorization': 'Bearer <bearer token>', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)
jsonData = res.json

Response


{
 "response": {
   "result": {
     "per_page": 15,
     "pages": 1,
     "total": 3,
     "page": 1,
     "expenses": [
       {
         // same format as single expense
       },
       {
         // same format as single expense
       },
       {
         // same format as single expense
       }
      ]
    }
  }
}