Staff access

Staff do not have access to the API calls listed below.

invoice.create

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

Notes

• 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.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.create">
  <invoice>
    <client_id>13</client_id>              # Client being invoiced

    <number>FB00004</number>               # Number, as it appears on the invoice (Optional)
    <status>draft</status>                 # One of sent, viewed, paid, or draft [default]
    <date>2007-06-23</date>                # If not supplied, defaults to today's date (Optional)
    <po_number>2314</po_number>            # Purchase order number (Optional)
    <discount>10</discount>                # Percent discount (Optional)
    <notes>Due upon receipt.</notes>       # Notes (Optional)
    <terms>Payment due in 30 days.</terms> # Terms (Optional)

    <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)

    <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>8</tax1_percent>             # (Optional)
        <tax2_percent>6</tax2_percent>             # (Optional)
      </line>
    </lines>
  </invoice>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response 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.

Notes

• If you do not specify a <lines> element, the existing lines will remain unchanged.

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.

Notes

• You can use the <url> value to provide your customers with a direct link to their invoice.

Request

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

Response

<?xml version="1.0"?>
<response status="ok">
  <invoice>
    <invoice_id>344</invoice_id>
    <client_id>3</client_id>

    <number>FB00004</number>
    <amount>45.6</amount> # Total invoice amount, taxes inc. (Read Only)
    <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>

    <url>http://sample.freshbooks.com/inv/167-344-7c7q2</url> # (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>

    <lines>
      <line>
        <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>8</tax1_percent>
        <tax2_percent>6</tax2_percent>
      </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.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="invoice.list">
  <client_id>3</client_id>            # Filter by client (Optional)
  <recurring_id>10</recurring_id>     # Filter by recurring id (Optional)
  <status>draft</status>              # Filter by status (Optional)
  <date_from>2007-01-01</date_from>   # Return invoices dated after this arg (Optional)
  <date_to>2007-04-01</date_to>       # Return invoices dated before this arg (Optional)

  <page>1</page>                      # Page number to return, default is 1 (Optional)
  <per_page>10</per_page>             # Number of results per page, default is 25 (Optional)
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <invoices page="1" per_page="10" pages="4" total="47">
    <invoice>
      <invoice_id>344</invoice_id>
      <number>FB00004</number>
      <client_id>3</client_id>
      <recurring_id></recurring_id>
      <organization>ABC Corp</organization>
      <amount>45.6</amount>
      <date>2007-06-23</date>
    </invoice>
    <invoice>
      <invoice_id>287</invoice_id>
      <number>FB00001<number>
      <client_id>3</client_id>
      <recurring_id>19</recurring_id>
      <organization>ABC Corp</organization>
      <amount>93.41</amount>
      <date>2007-03-17</date>
    </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"/>

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.

Please 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"/>