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:
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.