Working with Expenses in FreshBooks

Overview

The following operations allow you to work with expenses. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with expenses, see Sample configuration.

Operation	Description
createExpense	Creates an expense.
deleteExpense	Deletes an expense.
getExpense	Retrieves an expense.
listExpense	Lists expenses.
updateExpense	Updates an expense.

Operation details

This section provides details on the operations.

Creating an expense

The createExpense operation creates a new expense specifically for a client and, optionally, one of their projects, or keeps it generalized for a number of clients.

createExpense

<freshbooks.createExpense>
    <staffId>{$ctx:staffId}</staffId>
    <status>{$ctx:status}</status>
    <vendor>{$ctx:vendor}</vendor>
    <categoryId>{$ctx:categoryId}</categoryId>
    <projectId>{$ctx:projectId}</projectId>
    <date>{$ctx:date}</date>
    <clientId>{$ctx:clientId}</clientId>
    <compoundTax>{$ctx:compoundTax}</compoundTax>
    <amount>{$ctx:amount}</amount>
    <tax1Name>{$ctx:tax1Name}</tax1Name>
    <tax1Amount>{$ctx:tax1Amount}</tax1Amount>
    <tax1Percent>{$ctx:tax1Percent}</tax1Percent>
    <tax2Name>{$ctx:tax2Name}</tax2Name>
    <tax2Amount>{$ctx:tax2Amount}</tax2Amount>
    <tax2Percent>{$ctx:tax2Percent}</tax2Percent>
    <notes>{$ctx:notes}</notes>
</freshbooks.createExpense>

Properties

staffId: The staff ID. It is a required field only for admin users. It is ignored for staff using the API.
status: Status ID of the expense.
vendor: Associated vendor's name.
categoryId: Required - The ID associated with categories like Automobile, Contractors, etc.
projectId: ID of the related project.
date: Applicable date.
clientId: ID assigned to this client.
compoundTax: Whether the tax is compound ("true" or "false").
amount: Required - Associated cost.
tax1Name: Name of tax 1.
tax1Amount: Amount of tax 1.
tax1Percent: Percentage of tax 1.
tax2Name: Name of tax 2.
tax2Amount: Amount of tax 2.
tax2Percent: Percentage of tax 2.
notes: Notes associated with the expense report.

Sample request

Following is a sample REST/XML request that can be handled by the createExpense operation.

Sample Request for createExpense

<createExpense>
   <arbitraryPassword></arbitraryPassword>
   <apiUrl>https://sansu.freshbooks.com</apiUrl>
   <authenticationToken>c361a63c74565df19412fa8051ea605a6d</authenticationToken>
   <staffId>1</staffId>
   <status>1</status>
   <vendor>Sun Tzu Auto</vendor>
   <categoryId>5</categoryId>
   <projectId>19410</projectId>
   <date>2014-05-22</date>
   <clientId>99962</clientId>
   <compoundTax></compoundTax>
   <amount>2000</amount>
   <tax1Name>VAT</tax1Name>
   <tax1Amount>200</tax1Amount>
   <tax1Percent>10</tax1Percent>
   <tax2Name>GST</tax2Name>
   <tax2Amount>200</tax2Amount>
   <tax2Percent>10</tax2Percent>
   <notes>Expense Test</notes>
</createExpense>

Deleting an expense

The deleteExpense operation deletes an existing expense.

deleteExpense

<freshbooks.deleteExpense>
	<expenseId>{$ctx:expenseId}</expenseId>
</freshbooks.deleteExpense>

Properties

expenseId: Required - The ID of the expense to be deleted.

Sample request

Following is a sample REST/XML request that can be handled by the deleteExpense operation.

Sample Request for deleteExpense

<deleteExpense>
   <arbitraryPassword></arbitraryPassword>
   <apiUrl>https://sansu.freshbooks.com</apiUrl>
   <authenticationToken>c361a63c7456519412fa8051ea6d605a6d</authenticationToken>
   <expenseId>170494</expenseId>
</deleteExpense>

Retrieving an expense

The getExpense operation returns the complete expense details associated with the given expense ID.

getExpense

<freshbooks.getExpense>
	<expenseId>{$ctx:expenseId}</expenseId>
</freshbooks.getExpense>

Properties

expenseId: Required - The ID of the expense whose details are to be retrieved.

Sample request

Following is a sample REST/XML request that can be handled by the getExpense operation.

Sample Request for getExpense

<getExpense>
   <arbitraryPassword></arbitraryPassword>
   <apiUrl>https://sansu.freshbooks.com</apiUrl>
   <authenticationToken>c361ghja63c7456519412fa8051ea605a6d</authenticationToken>
   <expenseId>170494</expenseId>
</getExpense>

Listing expense

The listExpense operation returns a list of expense summaries. The results can optionally be filtered by client ID, category ID, project ID, date from, date to, or vendor. This operation uses pagination.

listExpense

<freshbooks.listExpense>
	<folder>{$ctx:folder}</folder>
    <order>{$ctx:order}</order>
    <page>{$ctx:page}</page>
    <dateTo>{$ctx:dateTo}</dateTo>
    <vendor>{$ctx:vendor}</vendor>
    <categoryId>{$ctx:categoryId}</categoryId>
    <perPage>{$ctx:perPage}</perPage>
    <projectId>{$ctx:projectId}</projectId>
    <dateFrom>{$ctx:dateFrom}</dateFrom>
    <clientId>{$ctx:clientId}</clientId>
</freshbooks.listExpense>

Properties

folder: The folder to filter the results by.
order: The order in which the results should be presented.
page: The page of results to be returned.
dateTo: The end date to which the results should be filtered.
vendor: The vendor to filter results by.
categoryId: The category ID to filter results by.
perPage: The number of results to be returned per page.
projectId: The project ID to filter results by.
dateFrom: The date from which the results should be filtered.
clientId: The ID of the client whose expenses are to be listed.

Sample request

Following is a sample REST/XML request that can be handled by the listExpense operation.

Sample Request for listExpense

<listExpense>
   <arbitraryPassword></arbitraryPassword>
   <apiUrl>https://sansu.freshbooks.com</apiUrl>
   <authenticationToken>c361a63c745651941df2fa8051ea605a6d</authenticationToken>
   <folder></folder>
   <order></order>
   <page></page>
   <dateTo></dateTo>
   <vendor></vendor>
   <categoryId></categoryId>
   <perPage></perPage>
   <projectId></projectId>
   <dateFrom></dateFrom>
   <clientId></clientId>
</listExpense>

Updating an expense

The updateExpense operation updates an existing expense. Any expense fields left out of the request will remain unchanged.

updateExpense

<freshbooks.updateExpense>
    <expenseId>{$ctx:expenseId}</expenseId>
    <staffId>{$ctx:staffId}</staffId>
    <status>{$ctx:status}</status>
    <vendor>{$ctx:vendor}</vendor>
    <categoryId>{$ctx:categoryId}</categoryId>
    <projectId>{$ctx:projectId}</projectId>
    <date>{$ctx:date}</date>
    <clientId>{$ctx:clientId}</clientId>
    <compoundTax>{$ctx:compoundTax}</compoundTax>
    <amount>{$ctx:amount}</amount>
    <tax1Name>{$ctx:tax1Name}</tax1Name>
    <tax1Amount>{$ctx:tax1Amount}</tax1Amount>
    <tax1Percent>{$ctx:tax1Percent}</tax1Percent>
    <tax2Name>{$ctx:tax2Name}</tax2Name>
    <tax2Amount>{$ctx:tax2Amount}</tax2Amount>
    <tax2Percent>{$ctx:tax2Percent}</tax2Percent>
    <notes>{$ctx:notes}</notes>
</freshbooks.updateExpense>

Properties

expenseId: Required - ID of the expense you are updating.
staffId: The staff ID. It is a required field only for admin users. It is ignored for staff using the API.
status: Status ID of the expense.
vendor: Associated vendor's name.
categoryId: Required - The ID associated with categories like Automobile, Contractors, etc.
projectId: ID of the related project.
date: Applicable date.
clientId: ID assigned to this client.
compoundTax: Whether the tax is compound ("true" or "false").
amount: Required - Associated cost.
tax1Name: Name of tax 1.
tax1Amount: Amount of tax 1.
tax1Percent: Percentage of tax 1.
tax2Name: Name of tax 2.
tax2Amount: Amount of tax 2.
tax2Percent: Percentage of tax 2.
notes: Notes associated with the expense report.

Sample request

Following is a sample REST/XML request that can be handled by the updateExpense operation.

Sample Request for updateExpense

<updateExpense>
   <arbitraryPassword></arbitraryPassword>
   <apiUrl>https://sansu.freshbooks.com</apiUrl>
   <authenticationToken>c361a63c745651sdf9412fa8051hea60h5a6d</authenticationToken>
   <expenseId>170494</expenseId>
   <staffId>1</staffId>
   <status>1</status>
   <vendor>Tatanka Auto</vendor>
   <categoryId>3</categoryId>
   <projectId>19410</projectId>
   <date>2014-05-22</date>
   <clientId>99962</clientId>
   <compoundTax></compoundTax>
   <amount>30000</amount>
   <tax1Name>VAT</tax1Name>
   <tax1Amount>200</tax1Amount>
   <tax1Percent>10</tax1Percent>
   <tax2Name>GST</tax2Name>
   <tax2Amount>200</tax2Amount>
   <tax2Percent>10</tax2Percent>
   <notes>Expense Test</notes>
   <compoundTax>false</compoundTax>
</updateExpense>

Sample configuration

Following is a sample proxy service that illustrates how to connect to FreshBooks with the init operation and use the createExpense operation. The sample request for this proxy can be found in createExpense sample request. You can use this sample as a template for using other operations in this category.

Sample Proxy

<?xml version="1.0" encoding="UTF-8"?>
	<proxy xmlns="http://ws.apache.org/ns/synapse" name="freshbooks_createExpense" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
	 <target>
	 <inSequence onError="faultHandlerSeq">
      <property name="arbitraryPassword" expression="//arbitraryPassword/text()"/>
      <property name="apiUrl" expression="//apiUrl/text()"/>
      <property name="authenticationToken" expression="//authenticationToken/text()"/>
      <property name="tax2Name" expression="//tax2Name/text()"/>
      <property name="staffId" expression="//staffId/text()"/>
      <property name="tax1Amount" expression="//tax1Amount/text()"/>
      <property name="status" expression="//status/text()"/>
      <property name="vendor" expression="//vendor/text()"/>
      <property name="categoryId" expression="//categoryId/text()"/>
      <property name="tax1Percent" expression="//tax1Percent/text()"/>
      <property name="projectId" expression="//projectId/text()"/>
      <property name="date" expression="//date/text()"/>
      <property name="clientId" expression="//clientId/text()"/>
      <property name="compoundTax" expression="//compoundTax/text()"/>
      <property name="tax2Amount" expression="//tax2Amount/text()"/>
      <property name="amount" expression="//amount/text()"/>
      <property name="tax1Name" expression="//tax1Name/text()"/>
      <property name="tax2Percent" expression="//tax2Percent/text()"/>
      <property name="notes" expression="//notes/text()"/>
	  <property name="compoundTax" expression="//compoundTax/text()" />
      <freshbooks.init>
         <arbitraryPassword>{$ctx:arbitraryPassword}</arbitraryPassword>
         <apiUrl>{$ctx:apiUrl}</apiUrl>
         <authenticationToken>{$ctx:authenticationToken}</authenticationToken>
      </freshbooks.init>
      <freshbooks.createExpense>
         <tax2Name>{$ctx:tax2Name}</tax2Name>
         <staffId>{$ctx:staffId}</staffId>
         <tax1Amount>{$ctx:tax1Amount}</tax1Amount>
         <status>{$ctx:status}</status>
         <vendor>{$ctx:vendor}</vendor>
         <categoryId>{$ctx:categoryId}</categoryId>
         <tax1Percent>{$ctx:tax1Percent}</tax1Percent>
         <projectId>{$ctx:projectId}</projectId>
         <date>{$ctx:date}</date>
         <clientId>{$ctx:clientId}</clientId>
         <compoundTax>{$ctx:compoundTax}</compoundTax>
         <tax2Amount>{$ctx:tax2Amount}</tax2Amount>
         <amount>{$ctx:amount}</amount>
         <tax1Name>{$ctx:tax1Name}</tax1Name>
         <tax2Percent>{$ctx:tax2Percent}</tax2Percent>
         <notes>{$ctx:notes}</notes>
	  </freshbooks.createExpense>
      <filter source="$axis2:HTTP_SC" regex="^[^2][0-9][0-9]">
            <then>
               <switch source="$axis2:HTTP_SC">
                  <case regex="400">
                     <property name="ERROR_CODE" value="600400"/>
                     <property name="ERROR_MESSAGE" expression="//*[local-name()='error']"/>
                  </case>
                  <case regex="401">
                     <property name="ERROR_CODE" value="600401"/>
                     <property name="ERROR_MESSAGE" expression="//*[local-name()='error']"/>
                  </case>
                  <case regex="403">
                     <property name="ERROR_CODE" value="600403"/>
                     <property name="ERROR_MESSAGE" expression="//*[local-name()='error']"/>
                  </case>
                  <case regex="404">
                     <property name="ERROR_CODE" value="600404"/>
                     <property name="ERROR_MESSAGE" expression="//*[local-name()='error']"/>
                  </case>
                  <case regex="500">
                     <property name="ERROR_CODE" value="600500"/>
                     <property name="ERROR_MESSAGE" expression="//*[local-name()='error']"/>
                  </case>
                  <default>
                     <property name="ERROR_CODE" expression="$axis2:HTTP_SC"/>
                     <property name="ERROR_MESSAGE" expression="//*[local-name()='error']"/>
                  </default>
               </switch>
               <sequence key="faultHandlerSeq"/>
            </then>
         </filter>
	   <respond/>
	 </inSequence>
	  <outSequence>
	    <send/>
	  </outSequence>
	 </target>
   <description/>
  </proxy>

Working with Expenses in FreshBooks

Overview

Operation details

Creating an expense

Properties

Sample request

Related FreshBooks documentation

Deleting an expense

Properties

Sample request

Related FreshBooks documentation

Retrieving an expense

Properties

Sample request

Related FreshBooks documentation

Listing expense

Properties

Sample request

Related FreshBooks documentation

Updating an expense

Properties

Sample request

Related FreshBooks documentation

Sample configuration