Multi-Currency with the API

by Paul Osman in on January 14, 2010

Yesterday we were thrilled to announce that multi-currency support has been added to FreshBooks!

Today, we're equally happy to announce that you can take advantage of these new features using the API. You can now create invoices, recurring profiles, estimates, payments and apply client credit in multiple currencies.

Invoices, Estimates, Recurring Profiles and Payments

Invoice, estimate, recurring profile and payment responses will now contain an element containing the ISO 4217 currency code. In order to create an invoice, estimate, recurring profile, or payment with a specific currency code, just include this element in your create request body. For example:

<?xml version="1.0" encoding="utf-8"?>
<request method="estimate.create">
  <estimate>
	<client_id>1</client_id>
	<currency_code>EUR</currency_code>
	<lines>
	  <line>
		<name>Yard Work</name>
		<unit_cost>10</unit_cost>
		<quantity>4</quantity>
	  </line>
    </lines>
  </estimate>
</request>

If the currency code element is not present, it will default to the base currency of your FreshBooks system (as configured in your FreshBooks account settings).

Client Credits

Because a client can have multiple credits applied to their account, client.get responses will now contain a new element called 'credits'. This element will contain child elements, one per credit, detailing the amount and the currency of each credit applied. For example:

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <client>
    <client_id>1</client_id>
    ...
    <credit currency="CAD" deprecated="true">450.50</credit>
    <credits>
      <credit currency="CAD">450.50</credit>
      <credit currency="USD">150.25</credit>
    </credits>
    ...
  </client>
</response>

It is important to note that the old credit element will only report credits in the base currency and therefore has been marked as deprecated. To get credits in all currencies, use the 'credits' element.

Migrating your integration to Multi-Currency

If you have a current integration with FreshBooks, it will continue to work unchanged. Currency codes are not required. FreshBooks will continue to operate as you previously expected. However, if your users begin to use multicurrency in FreshBooks and you report fiscal figures, you must upgrade your integration to support the currency codes we report. Otherwise, you may accidentally combine figures from two different currencies and report incorrectly.

1 comments

Eating our own dog food

by Diana Clarke in on November 11, 2009

About a year ago, we started to really focus on what the future of development at FreshBooks would look like.

Aside from the obvious concerns about code quality and maintainability, we had an additional requirement to keep in mind: integrations! We integrate with tons and tons of other applications, so while FreshBooks the web application is still our flagship, we needed to stop developing from its point of view, and embrace that fact that our web application is just one of many FreshBooks data consumers. We needed to start eating our own dog food.

The mantra is simple — anything we develop for FreshBooks the web application should also be, by definition, available for third parties to consume. To accomplish this, we are in the process of decoupling our web application from the database/business logic, and instead consuming a new FreshBooks API called Evolve¹. Since our own application is driving the requirements, the resulting API is more complete and performant than previous passes. I look forward to the day when I can announce Evolve's public debut, but for now it's strictly internal.

Stay tuned for more technical details and a series of posts on how we got here. In the mean time, I'll close with a quick example of FreshBooks eating its own dog food to render a capacity meter by calling out to Evolve for the data it needs. The new API is a RESTful one that supports serialization in both XML and JSON. It's written in Python and uses Pylons and SQLAlchemy — there's a bunch we could discuss there.

The capacity meter on the documents tab.


$ curl -u [auth] https://[evolve]/documents/capacities.json

{
  "response": {
    "result": {
      "capacity": {
        "available": 0.34,
        "size": 2.0,
        "unit": "MB",
        "used": 1.66
      }
    }
  }
}

$ curl -u [auth] https://[evolve]/documents/capacities.xml

<response>
  <result>
    <capacity>
      <unit>MB</unit>
      <size>2.0</size>
      <available>0.34</available>
      <used>1.66</used>
    </capacity>
  </result>
</response>

Evolve went into production a couple of weeks ago, quietly ripping the backend out of our web application, one data silo at a time. I'm proud. What do you think? Feedback? Questions?

¹Nope, not implying that we were Neanderthals before -- I name all my apps after Ani Difranco.

5 comments

API Updates: Project Staff, Custom Emails and payment.delete

by Paul Osman in API Additions, Development on October 23, 2009

On Wednesday we released some pretty exciting updates to our API and wanted to make sure you were aware of them.

Project Results

If you are an administrator or a staff member who is assigned as a project manager to a project, project.get and project.list methods now return the ids of users who are assigned to that project. Up until now it was impossible to determine if a user was assigned to a project when listing them. Because of this, our OS X time tracker for instance would list all projects that a user could see, not just the ones that they were assigned to. If the user clicked on "Submit" after selecting a project that they weren't assigned to, they would get an error because you can't track time to a project you aren't assigned to. What a headache! See the updated documentation for details.

Custom Emails

You can now send custom email messages with invoice.sendByEmail and estimate.sendByEmail. Just include both a subject and a message element in your request. You can use any of the variables that are available when customizing messages within FreshBooks (i.e. ::invoice link::, ::payment amount::, ::estimate link::). See examples on the invoice and estimate documentation pages.

Delete Payments

We've added a payment.delete method. This will allow you to permanently delete payments. If the payment being deleted was made against an invoice, the status of the invoice will be updated. Check out the documentation.

So there you go, three great new features!

1 comments