Introducing Return to Merchant

by Owen in API Additions 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.

1 comments

Updates to recurring billing

by Sunir in API Additions on February 11, 2009

We made some big updates to recurring billing in today’s release that will make life much easier for many of you. If you’re running a subscription-based billing service on top of FreshBooks, please take note:

Recurring invoices now default to auto-bill
We have changed the default so that recurring invoices automatically bill client credit cards for future invoices, rather than asking the client if they’d like this. We feel this fits better with everyone’s expectations of what should happen. You should expect less confusion around customers needing to enter credit cards multiple times. Note that you will need to purchase enough auto-bills in your system.

Recurring profiles starting today will invoice immediately.
Previously, you could only create recurring profiles starting on a future date. Now, if you create a recurring profile with today’s date, an invoice will be created and sent immediately. The response XML includes the created invoice_id.

This means you can set up a recurring profile immediately at the time of initial purchase, and then immediately redirect your customer to pay the invoice. This should dramatically speed up the time it takes for you get paid, as well as lower attrition rates on payment.

Hopefully these changes will really help your business. Let us know how it goes!

Enjoy!

0 comments

Expense categories added!

by Mike G in API Additions on December 17, 2008

Well that makes sense now. Now the little <category_id> on expense operations means something. With the introduction of Expense Categories to the API, you now have the flexibility to manipulate them freely.  This includes any taxes that may apply.

The taxation mechanism is flexible to your requirements, but it’s also a relationship that you are required to maintain.  <tax1> and <tax2> can be used to track your own tax ID against chosen categories, and then calculated and displayed on the individual expense via <tax1_name>, <tax1_percent> and <tax1_amount>.  Three more fields for <tax2_ now appear on expense.get operations as well, and match the preceeding format.

These changes have been reflected in the Expenses API documentation, and a new link for categories has been added.  Please feel free to discuss or ask questions in the forum.

0 comments