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

Expenses

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

Access Requirements

AccessRequires Authorization
Scopesuser: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”.

codenamedescription
0internal-internal- rather than client
1outstandinghas client, needs to be applied to an invoice
2invoicedhas client, attached to an invoice
4recoupedhas client, attached to an invoice, and paid

Includes

Include NameDescription
attachmentIncludes attachment details assocatied with expense receipts
categoryInclude expense category in expense
expense_profileInclude expense profile info in expense
projectInclude related projects in expense
accountInclude account info in expense

Filters

Filter TypeNameFieldDescription
Equalsexpenseidexpenseidmatches exact expenseid
Inexpenseidsexpenseidmatches list of expenseids, one specified per query arg
Equalsclientidclientidmatches exact clientid
Inclientidsclientidmatches list of clientids, one specified per query arg
NotEqualsclientid_notclientidany clientid but the parameter
Equalsstaffidstaffidmatches exact staffid
Instaffidsstaffidmatches list of staffids, one specified per query arg
Equalsprofileidprofileidmatches exact profileid
Inprofileidsprofileidmatches list of profileids, one specified per query arg
Equalscategoryidcategoryidmatches exact categoryid
Incategoryidscategoryidmatches list of categoryids, one specified per query arg
Equalsprojectidprojectidmatches exact projectid
Inprojectidsprojectidmatches list of projectids, one specified per query arg
Equalshas_receipthas_receipttrue/false expense has related receipt
Betweenamount_minamountamount greater than or equal to parameter
Betweenamount_maxamountamount less than parameter
Betweendate_mindatedate greater than or equal to parameter, YYYY-MM-DD format
Betweendate_maxdatedate less than parameter, YYYY-MM-DD format
Betweenupdated_minupdatedupdated date greater than or equal to parameter, YYYY-MM-DD format
Betweenupdated_maxupdatedupdated date less than parameter, YYYY-MM-DD format
Likevendorvendorvendors containing the parameter
Equalsvendor_eqvendorexact match of vendor field
Likenotesnotesnotes containing the parameter
Likecategory _namecategorycategory containing the parameter
Boolis_cogsis_cogsis cost of goods sold or not (DEPRECATED See update)
Intransactionidstransactionidmatches list of transactionids, one specified per query arg
Equalsaccountidaccountidexact match of accountid
Inaccountidsaccountidmatches list of accountids, one specified per query arg
Equalsaccount _namenamematches exact name
Equalcategory _parentidspecialmatches either exact categoryid or parentid

Field Descriptions

underlined fields are required on creation

FieldTypeDescription
accountidintid of expense account if applicable
account_namestringname of related account if applicable
accounting _systemidstringunique id for system
amountobjectTotal amount of the expense
– amountstringstring-decimal amount of the expense
– codestring3-letter currency code
background_jobidint(internal) id for related background job if applicable
bank_namestringname of bank expense was imported from, if applicable
categoryidintid of related expense category
clientidintid of related client if applicable
compounded_taxboolDeprecated. true/false tax2 was a compound tax
datedatedate of expense, YYYY-MM-DD format
expenseidintunique to this business id for expense
ext_invoiceidintid of related contractor invoice if applicable
ext_systemidintid of related contractor system if applicable
has_receiptbooltrue/false has receipt attached
idintduplicate of expenseid
invoiceidintid of related invoice if applicable
isduplicatebooltrue/false is duplicated expense
markup_percentstringstring-decimal, note of percent to mark expense up
notesstringnotes about expense
profileidintid of related profile if applicable
projectidintid of related project if applicable
staffidintid of related staff member if applicable
statusintvalues from expense status table
taxAmount1objectThe total for first tax applied to the subtotal amount of the expense
– amountstringstring-decimal amount
– codestring3-letter currency code
taxName1stringname of first tax
taxPercent1stringstring-decimal tax amount – indicates the maximum tax percentage for this expense, this does not add tax to the expense, instead use taxAmount1
taxAmount2objectThe total for second tax applied to the subtotal amount of the expense
– amountstringstring-decimal amount
– codestring3-letter currency code
taxName2stringname of second tax
taxPercent2stringstring-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
transactionidintid of related transaction if applicable
updateddatetimetime invoice last updated at, YYYY-MM-DD HH:MM:SS format
vendorstringname of vendor
vis_stateint0 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": {}
 }