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 (DEPRECATED See update) |
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 |
---|---|---|
accountid | int | id of expense account if applicable |
account_name | string | name of related account if applicable |
accounting _systemid | string | unique id for system |
amount | object | Total amount of the expense |
– amount | string | string-decimal amount of the expense |
– code | string | 3-letter currency code |
background_jobid | int | (internal) id for related background job if applicable |
bank_name | string | name of bank expense was imported from, if applicable |
categoryid | int | id of related expense category |
clientid | int | id of related client if applicable |
compounded_tax | bool | Deprecated. true/false tax2 was a compound tax |
date | date | date of expense, YYYY-MM-DD format |
expenseid | int | unique to this business id for expense |
ext_invoiceid | int | id of related contractor invoice if applicable |
ext_systemid | int | id of related contractor system if applicable |
has_receipt | bool | true/false has receipt attached |
id | int | duplicate of expenseid |
invoiceid | int | id of related invoice if applicable |
isduplicate | bool | true/false is duplicated expense |
markup_percent | string | string-decimal, note of percent to mark expense up |
notes | string | notes about expense |
profileid | int | id of related profile if applicable |
projectid | int | id of related project if applicable |
staffid | int | id of related staff member if applicable |
status | int | values from expense status table |
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 |
taxName1 | string | name of first tax |
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 |
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 |
taxName2 | string | name of second 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 |
transactionid | int | id of related transaction if applicable |
updated | datetime | time invoice last updated at, YYYY-MM-DD HH:MM:SS format |
vendor | string | name of vendor |
vis_state | int | 0 for active, 1 for deleted |
List Expenses
Request: GET https://api.freshbooks.com/accounting/account/<accountid>/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 Single Expense
Request: GET "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<expenseid>"
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"
Response:
{
"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 Expense
Request: PUT "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<expenseid>"
{
"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 Expense
Request: PUT "https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<expenseid>"
{
"expense": {
"vis_state": 1
}
}
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
}
]
}
}
}
Get Single Expense
Request: GET
"https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<expenseid>"
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 Expense
Request: PUT
"https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<expenseid>"
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 Expense
Request: PUT
https://api.freshbooks.com/accounting/account/<accountid>/expenses/expenses/<expenseid>
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": {}
}