Skip to Main Content
×
Freshbooks
Official App
Free – Google Play
Get it
FreshBooks is Loved by American Small Business Owners
FreshBooks is Loved by Canadian Small Business Owners
FreshBooks is Loved by Small Business Owners in the UK
Dev Blog

Introducing Return to Merchant

by Owen on March 26/2009

For those of you out there who use FreshBooks as part of a storefront, we have a new feature just for you. FreshBooks invoices created through the API can now have a “return-to-merchant” link. When one of your customers pays an invoice that has a link, they’re given the option to return to your site via whatever URL you specify when you create the invoice. This feature is only available through the API (for now) – try it out and let us know what you think.

Creating an invoice with a return-to-merchant link.

If you already have code that creates new invoices, adding return-to-merchant links when creating an invoice means adding one more element to the <invoice /> element in your request: <return_uri>YOUR URL HERE</return_uri>. The URI from your API request will be used verbatim, so remember to include the http:// or https:// at the beginning.

<?xml version="1.0" encoding="utf-8"?>


2



http://invoices.example.com/thanks-for-paying


The <return_uri /> element is supported in invoice.update, and it’s returned from invoice.get requests.

What will your customers see?

The return-to-merchant link is shown to your customers only after they’ve paid their invoices. The payment summary page has an extra link, which will send them to… well, anywhere you want. We’ve also streamlined the payment landing page so that it acts more like the rest of FreshBooks: it now has a clear confirmation message, then the next steps to take, and finally extra information.

Recurring profiles can have return-to-merchant links too.

You can include <return_uri />s in recurring.create and recurring.update, too. When an invoice is created from a recurring profile, some variable substitution takes place, so that the generated link can include a reference back to the invoice.

Let’s say you set your recurring profile’s return_uri to

http://invoices.example.com/invoices/::invoice id::/paid

The invoice ID (invoice_id in the invoice.get API response) of the generated invoices will show up in each invoice’s <recurring_uri> – for example, if the generated invoice ID is 16, then the return-to-merchant link will point to

http://invoices.example.com/invoices/16/paid

This works with ::invoice number:: and the invoice_number of the generated invoices, too.

What about…

There are lots of things we’d like to do with this in the future to make the FreshBooks API support more scenarios. I’m sure some of you have software you’d like to have notified when a customer pays an invoice, for example – that comes up a lot with PayPal’s basic integration, which uses a similar “return to merchant” feature to implement notifications. We’d love to hear other ways of extending the API to better fit how you want to use FreshBooks.