Multi-Currency with the API
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).
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="https://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.