Integration with billing software

Hi! I am Jess, a product manager from a billing and subscription platform. I am currently working on an API integration between FreeAgent and our product and I was hoping to get some feedback on the process I was hoping to use. The integration with FreeAgent, would allow our customers to sync all of their invoices, credit notes and payments over to their FreeAgent account. From my current understanding of the API documentation these would be done in the following ways:

Syncing Invoices

An API request will need to be sent to create the invoice in FreeAgent. Invoices need to be created for a specific contact, so this will also need to be created if it hasn’t already. As customers are notified in our product when their invoice is ready we will not need to notify them again via FreeAgent. To make sure this doesn’t happen all of the email attributes will be set to ‘false’ when the invoice is created. The invoice will then need to be updated using an API request to set the status from draft to open. All invoices will be created with a ‘0’ for the payment terms in days attribute as customers will be charged for their invoices when they are sent.

Syncing Credit notes

An API request will need to be sent to create a credit note in FreeAgent. Credit notes need to be created for a specific contact, so this will also need to be created if it hasn’t already. If the credit note has been created as an invoice refund, the invoice will need to be updated and the status changed to ‘refunded’ once the credit note has been paid.

Syncing payments and refunds

During the integration process, we will create a new bank account in the customers FreeAgent account for all transactions relating to our product. When payments are made or refunds are processed, an API request will be sent to create a bank transaction explanation relating to the invoice or create note that is being paid. It will need to include the id of the invoice or credit note it relates to.

Once the bank transaction explanation has been created, the invoice or credit note it is linked to need to be updated so the status reads paid.

Writing-off an invoice

From my understanding, an invoice can be written-off by sending an update request and setting the status to written-off and providing the date the invoice was written off.

Updating a written-off invoice

For invoices that are written-off but then recovered, an API request will be sent to update the status of the invoice from written-off to paid.

I hope I’ve understood your API documentation, if I’ve misunderstood any aspects of your API please let me know.



Hi Jess,

Thanks for your message on our forum and how very exciting to hear that you’re embarking on the process of building an integration with FreeAgent :tada: While we have a range of excellent FreeAgent API experts on this forum, we tend to focus on the technical nitty-gritty (as engineers do! :sweat_smile:) , whereas it feels like the best people for you to talk to in the first instance would be our Partnerships Team — I’ve already checked with them and they’d be happy to chat. Could I ask you to e-mail and ask to be put in touch with them please? It might be handy if you include a link to this thread in your e-mail so that you don’t have to repeat all the details you’ve already so helpfully included here!

All the best,


Hi Ewa,

That’s great! I’ll get in touch with the support team.



1 Like