Invoices

Staff have access to the API calls listed below if the Invoices tab is enabled for staff. Staff users can only access invoices that belong to clients they are assigned to.

invoice.create

Create a new invoice complete with line items. If successful, returns the invoice_id of the newly created invoice.

  • If you don’t specify an invoice <number>, it will increment from the last one.
  • You may optionally specify a different address on the invoice; otherwise the address will be pulled from your client’s details.
  • You may optionally specify a <return_uri> element. If provided, users will be presented with a link to the URI when they pay the invoice. More details of the return_uri element are available on the blog.

Request

<request method="invoice.create">
  <invoice>
    <!-- Client being invoiced -->
    <client_id>13</client_id>
	<!-- (Optional) -->
	<contacts>
		<contact>
			<contact_id>14</contact_id>
		</contact>
	</contacts>
    <!-- Number, as it appears on the invoice (Optional) -->
    <number>FB00004</number>
    <!-- One of sent, viewed or draft [default] -->
    <status>draft</status>
    <!-- If not supplied, defaults to today's date (Optional) -->
    <date>2007-06-23</date>
    <!-- Purchase order number (Optional) -->
    <po_number>2314</po_number>
    <!-- Percent discount (Optional) -->
    <discount>10</discount>
    <!-- Notes (Optional) -->
    <notes>Due upon receipt.</notes>
    <!-- Currency Code, defaults to your base currency (Optional) -->
    <currency_code>CAD</currency_code>
    <!-- Language code, defaults to the client's language; see language.list for codes (Optional) -->
    <language>en</language>
    <!-- Terms (Optional) -->
    <terms>Payment due in 30 days.</terms>
    <!-- Return URI (Optional) -->
    <return_uri>http://example.com/account</return_uri>

    <first_name>John</first_name>              <!-- (Optional) -->
    <last_name>Smith</last_name>               <!-- (Optional) -->
    <organization>ABC Corp</organization>      <!-- (Optional) -->
    <p_street1></p_street1>                    <!-- (Optional) -->
    <p_street2></p_street2>                    <!-- (Optional) -->
    <p_city></p_city>                          <!-- (Optional) -->
    <p_state></p_state>                        <!-- (Optional) -->
    <p_country></p_country>                    <!-- (Optional) -->
    <p_code></p_code>                          <!-- (Optional) -->
    <vat_name></vat_name>     <!-- e.g. 'VAT Number' (Optional) -->
    <vat_number></vat_number> <!-- If set, shown with vat_name under client address (Optional) -->

    <lines>     <!-- Specify one or more line elements (Optional) -->
      <line>
        <name>Yard Work</name>                       <!-- (Optional) -->
        <description>Mowed the lawn.</description>   <!-- (Optional) -->
        <unit_cost>10</unit_cost>                    <!-- Default is 0 -->
        <quantity>4</quantity>                       <!-- Default is 0 -->
        <tax1_name>GST</tax1_name>                   <!-- (Optional) -->
        <tax2_name>PST</tax2_name>                   <!-- (Optional) -->
        <tax1_percent>5</tax1_percent>               <!-- (Optional) -->
        <tax2_percent>8</tax2_percent>               <!-- (Optional) -->
        <type>Item</type>                            <!-- (Optional) -->
     <!-- One of 'Item' or 'Time'. If omitted, the line's type defaults to 'Item' -->
      </line>
    </lines>
  </invoice>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <invoice_id>344</invoice_id>
</response>

invoice.update

Update an existing invoice with the given invoice_id. Any invoice fields left out of the request will remain unchanged.

  • If you do not specify a <lines> element, the existing lines will remain unchanged. If you do specify <lines> elements the original ones will be replaced by the new ones.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.update">
  <invoice>
    <invoice_id>344</invoice_id>            <!-- Invoice to update -->
    <!-- Remaining arguments same as invoice.create -->
  </invoice>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

invoice.get

Return the complete invoice details associated with the given invoice_id.

  • You can use the <url> value to provide your customers with a direct link to their invoice.
  • You can use the <links> element to provide your customers with direct links to the invoice for editing, viewing by the client and viewing by an administrator.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.get">
  <invoice_id>344</invoice_id>
</request>

Response

<?xml version="1.0"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <invoice>
    <invoice_id>344</invoice_id>
    <client_id>3</client_id>
	<contacts>
		<contact>
			<contact_id>0</contact_id>
		</contact>
	</contacts>
    <number>FB00004</number>
    <!-- Total invoice amount, taxes inc. (Read Only) -->
    <amount>45.6</amount>
    <!-- Outstanding amount on invoice from partial payment, etc. (Read Only) -->
    <amount_outstanding>0</amount_outstanding>
    <status>paid</status>
    <date>2007-06-23</date>
    <po_number></po_number>
    <discount>0</discount>
    <notes>Due upon receipt.</notes>
    <terms>Payment due in 30 days.</terms>
    <currency_code>CAD</currency_code>
    <folder>active</folder>
    <language>en</language>

    <url deprecated="true">https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ</url> <!-- (Read-only) -->
    <auth_url deprecated="true">https://2ndsite.freshbooks.com/invoices/344</auth_url> <!-- (Read-only) -->
    <links>
      <client_view>https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ</client_view> <!-- (Read-only) -->
      <view>https://2ndsite.freshbooks.com/invoices/344</view> <!-- (Read-only) -->
      <edit>https://2ndsite.freshbooks.com/invoices/344/edit</edit> <!-- (Read-only) -->
    </links>

    <return_uri>http://www.example.com/callback</return_uri> <!-- (Optional) -->
    <updated>2009-08-12 00:00:00</updated>  <!-- (Read-only) -->

    <recurring_id>15</recurring_id> <!-- (Read-only) -->

    <organization>ABC Corp</organization>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
    <p_street1>123 Fake St.</p_street1>
    <p_street2>Unit 555</p_street2>
    <p_city>New York</p_city>
    <p_state>New York</p_state>
    <p_country>United States</p_country>
    <p_code>553132</p_code>
    <vat_name></vat_name>
    <vat_number></vat_number>
    <staff_id>1</staff_id>
    <lines>
      <line>
        <line_id>1</line_id>  <!-- (Read Only) line id -->
        <amount>40</amount>
        <!-- Line amount, taxes/discount excluding. (Read Only) -->
        <name>Yard work</name>
        <description>Mowed the lawn</description>
        <unit_cost>10</unit_cost>
        <quantity>4</quantity>
        <tax1_name>GST</tax1_name>
        <tax2_name>PST</tax2_name>
        <tax1_percent>5</tax1_percent>
        <tax2_percent>8</tax2_percent>
        <type>Item</type>
      </line>
    </lines>
  </invoice>
</response>

invoice.delete

Delete an existing invoice.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.delete">
  <invoice_id>344</invoice_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

invoice.list

Returns a list of invoice summaries. Results are ordered by descending invoice_id.

Note: This method uses pagination.

  • The value used for ‘status’ can be ‘disputed’, ‘draft’, ‘sent’, ‘viewed’, ‘paid’, ‘auto-paid’, ‘retry’, ‘failed’ or the special status ‘unpaid’ which will retrieve all invoices with a status of ‘disputed’, ‘sent’, ‘viewed’, ‘retry’ or ‘failed’.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.list">
  <!-- Filter by client (Optional) -->
  <client_id>3</client_id>
  <!-- Filter by recurring id (Optional) -->
  <recurring_id>10</recurring_id>
  <!-- Filter by status (Optional) -->
  <status>draft</status>
  <!-- Returns invoices with a number like this arg (Optional) -->
  <number>FB00004</number>
  <!-- Return invoices dated after this arg (Optional) -->
  <date_from>2007-01-01</date_from>
  <!-- Return invoices dated before this arg (Optional) -->
  <date_to>2007-04-01</date_to>
  <!-- Return invoices modified after this arg (Optional) -->
  <updated_from>2007-01-01 00:00:00</updated_from>
  <!-- Return invoices modified before this arg (Optional) -->
  <updated_to>2007-01-02 00:00:00</updated_to>
  <!-- Page number to return, default is 1 (Optional) -->
  <page>1</page>
  <!-- Number of results per page, default is 25 (Optional) -->
  <per_page>10</per_page>
  <!-- One of 'active', 'archived', 'deleted' (Optional)-->
  <folder>active</folder>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <invoices page="1" per_page="10" pages="4" total="47">
    <invoice>
      <invoice_id>344</invoice_id>
      <client_id>3</client_id>
		<contacts>
			<contact>
				<contact_id>0</contact_id>
			</contact>
		</contacts>
      <number>FB00004</number>
      <amount>45.6</amount>
      <currency_code>CAD</currency_code>
      <language>en</language>
      <amount_outstanding>0</amount_outstanding>
      <status>paid</status>
      <date>2007-06-23</date>
      <folder>active</folder>
      <po_number></po_number>
      <discount>0</discount>
      <notes>Due upon receipt.</notes>
      <terms>Payment due in 30 days.</terms>
      <url deprecated="true">https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ</url>
      <auth_url deprecated="true">https://2ndsite.freshbooks.com/invoices/344</auth_url>
      <links>
        <client_view>https://2ndsite.freshbooks.com/view/St2gThi6rA2t7RQ</client_view>
        <view>https://2ndsite.freshbooks.com/invoices/344</view>
        <edit>https://2ndsite.freshbooks.com/invoices/344/edit</edit>
      </links>
      <return_uri>http://www.example.com/callback</return_uri>
      <updated>2009-08-12 09:00:00</updated>
      <recurring_id>15</recurring_id>
      <organization>ABC Corp</organization>
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <p_street1>123 Fake St.</p_street1>
      <p_street2>Unit 555</p_street2>
      <p_city>New York</p_city>
      <p_state>New York</p_state>
      <p_country>United States</p_country>
      <p_code>553132</p_code>
      <vat_name></vat_name>
      <vat_number></vat_number>
      <staff_id>1</staff_id>
      <lines>
        <line>
          <line_id>1</line_id>  <!-- (Read Only) line id -->
          <amount>40</amount>
          <name>Yard work</name>
          <description>Mowed the lawn</description>
          <unit_cost>10</unit_cost>
          <quantity>4</quantity>
          <tax1_name>GST</tax1_name>
          <tax2_name>PST</tax2_name>
          <tax1_percent>5</tax1_percent>
          <tax2_percent>8</tax2_percent>
          <type>Item</type>
        </line>
      </lines>
    </invoice>
    <invoice>
      ...
    </invoice>
    ...
  </invoices>
</response>

invoice.sendByEmail

Send an existing invoice to your client via e-mail. The invoice status will be changed to sent.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.sendByEmail">
  <invoice_id>344</invoice_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>
Custom Emails

If you would like to send a custom email, include a message and subject element. Note that both of these elements are required (one or the other will not work).

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.sendByEmail">
  <invoice_id>344</invoice_id>
  <subject>This is a custom subject!</subject>
  <message>You have a new invoice. Get it here: ::invoice link::</message>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

invoice.sendBySnailMail

Send an existing invoice to your client via snail mail. If you do not have enough stamps, the request will fail. If successful, the invoice status will be changed to sent.

Be careful with this method. This operation cannot be undone.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.sendBySnailMail">
  <invoice_id>344</invoice_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

invoice.lines.add

Adds (a) new line(s) to an existing invoice.

  • One or more lines may be added.
  • Do not specify line_id for any lines. (Ids will be assigned automatically). Use invoice.lines.update to change existing lines.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.lines.add">
  <invoice_id>111</invoice_id>
  <lines>
    <line>
      <amount>40</amount>
      <name>Yak Shaving</name>
      <description>Shaved the yak</description>
      <unit_cost>10</unit_cost>
      <quantity>4</quantity>
      <type>Item</type>
      ...
    </line>
    <line>
      <amount>23</amount>
      <name>Telephone Sanitizing</name>
      <description>Sanitized the telephone</description>
      <unit_cost>10</unit_cost>
      <quantity>2.30</quantity>
      <type>Item</type>
      ...
    </line>
  </lines>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <invoice_id>111</invoice_id>
  <lines>
    <line_id>45</line_id>
    <line_id>46</line_id>
  </lines>
</response>

Note: In most cases, the returned line_ids will correspond to the new lines in the order that they were sent, however, this behavior is not guaranteed and should not be relied on. If you absolutely require the ability to match the created line_ids with the data you sent, you should create each line in its own request, or use some unique value for each line to eliminate any ambiguity.

invoice.lines.delete

Deletes a single line from an existing invoice.

  • Only a single line can be deleted per request.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.lines.delete">
  <invoice_id>123</invoice_id>
  <line_id>2</line_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok"/>

invoice.lines.update

Updates (an) existing line(s) on an existing invoice.

  • One or more lines may be updated.
  • Only the provided fields will be updated. All others will be left unchanged.
  • line_id is mandatory for each line to be updated. Use invoice.lines.add to create new lines.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.lines.update">
  <invoice_id>99</invoice_id>
  <lines>
    <line>
      <line_id>1</line_id>
      <amount>50</amount>
      <name>Premium Yak Shaving</name>
      <unit_cost>12.50</unit_cost>
          ...
      </line>
      <line>
        <line_id>2</line_id>
        <amount>30</amount>
        <name>Advanced Telephone Sanitizing</name>
        <quantity>3.00</quantity>
        ...
      </line>
  </lines>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok"/>

Search

Developer Stuff

API Calls

Resources

Tour FreshBooks


  • FreshBooks
    35 Golden Ave, Suite 105
    Toronto, ON
    M6R 2J5 Canada
  • Toll Free (NA): 1-866-303-6061
    Freephone (UK): 0808-101-3408
    Freephone (Ireland): 1-800-949-046
    Phone: 416-481-6946
  • Rackspace
  • TRUSTe online privacy certification
Copyright © 2000-2013
FreshBooks is a service of 2ndSite Inc. All rights reserved.