API - metered/ recurring billing

Hi Andrew,

The API can do most of the things you need, however some functionality is
not yet exposed and might require you to manually change the data via the
web app.

1.multi-variable invoices i.e:

We are a mobile ads network that bills clients monthly. One client (client
A) may be advertising 3 games with us, each at a different price, we then
charge the Client the specified amount when we get that game an install. We
want to auto push this to the clients invoice, specifying the game we got
the install for, when it happened and what price we charged for it. At the
end of the month the invoice should be split out as follows:

  • Client A
  • game 1
  • installs on day 1 - price paid for installs

  • installs on day 2 - price paid for installs

  • total $ amount owed for Game 1
  • game 2
  • installs on day 1 - price paid for installs


  • total amount owed by Client A (Game 1 + Game 2 + Game 3) for specified
    time period (usually a month)

You can create such an invoice via the API for each of your clients along
with the invoice items. You can also update an existing invoice by
specifying the new invoice items to be added or the invoice items to be
updated. The format of the requests along with what input data we support
is available here https://dev.freeagent.com/docs/invoices. There you will
also find information about how to email an invoice using the API.

  1. recurring, metered invoices:
    We want to be able to send an invoice on a specified date to each client,
    however, the amount owed needs to be able to differ month to month.
    depending on the data we passed to you in section 1 (above). For example,
    in January Client A may owe us $10,000 but in February it may be $15,000.

Unfortunately we do not support creating recurring invoices via the API at
the moment. You can either create a normal invoice via the API, or manually
set up recurring profiles in FreeAgent and update the generated invoices
using the API.

  1. Complete autonomy.

I want to be able to send all the information required to set up and run
the invoice through the API. i.e not only the data on the items we are
charging for, but also the details on the client and when to invoice them.
So when we bring a new client on board we can simply pass all their data
through the API without one of us manually having to go into the freshbooks
system and make and account/ invoice ID for them,

You should be able to do this. Information on creating new contacts is
available here https://dev.freeagent.com/docs/contacts. Once you have a
contact you can create invoices for them as specified above, and email them
using the /v2/invoices/:id/send_email endpoint.

Ioan Dragos Serban