Listing Modified Invoices, Payments, and Clients

by Owen on August 12, 2009

We’ve rolled out modification tracking for three key API types: invoices, payments, and clients. Each of these types now has an updated field. This field is not writeable; FreshBooks will update it, automatically, whenever anyone makes a change, either through the web UI or the API. As with the existing date field, list requests can filter by updated time, using the updated_from and updated_to parameters. For mobile apps or for FreshBooks systems with a lot of invoices, this means that API clients can keep up with changes to invoice data without re-listing every invoice (or payment, or client) in the system periodically.

Example interaction

List request 1

<request method="invoice.list">
  <updated_from>2009-08-10 00:00:00</updated_from>
</request>

Response

<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <invoices page="1" per_page="25" pages="0" total="0"/>
</response>

Modify an invoice

<request method="invoice.update">
  <invoice>
    <invoice_id>00000000021</invoice_id>
    <discount>20</discount>
  </invoice>
</request>

List request 2

<request method="invoice.list">
  <updated_from>2009-08-10 00:00:00</updated_from>
</request>

Response

<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <invoices page="1" per_page="25" pages="1" total="1">
    <invoice>
      <invoice_id>00000000021</invoice_id>
      <number>0000021</number>
      <!-- ... -->
      <discount>20</discount>
      <!-- ... -->
      <updated>2009-08-10 12:53:42</updated>
      <lines>
        <!-- ... -->
      </lines>
    </invoice>
  </invoices>
</response>

The complete documentation is, as always, in our API docs, under the invoices, payments, and clients sections.

The other types in our API will be retrofitted with updated fields sooner or later. The three that we picked for this release cover most of the cases where API clients request large lists, so we wanted to get this out early, even with only three API types supported, to let people start using it sooner.

If you have any questions or suggestions, leave a comment, send us a note at .(JavaScript must be enabled to view this email address), or drop by our Developers forum.

Enjoy!