Invoice Statuses don't match the API docs :(


I’m using the API to pull up an invoice. Now, according to the API docs, the status of an invoice is:

One of the following:

Cancelled (also known as Written-off)

However, when I pull them out of the API, I’m seeing statuses like “Paid” and “Open”

Can someone shed some light on this - it’s very confusing, and it’s breaking our API wrapper (because it’s not getting the statuses it expects)


Hi @Matt_Roberts,

Thanks for your question! Looking at this portion of the docs afresh, I agree that this is confusing. What you’re seeing here is the difference between the directly controllable statuses (those listed in the docs), and those that come about from different actions in the application. For example, a “Sent” invoice that has been fully paid via bank transaction explanations will show as “Paid”. However you can’t directly create a “Paid” invoice via the invoice end points.

The valid statuses for an invoice are:

Scheduled To Email
Zero Value
Part written-off

I’ll schedule in a documentation update in the next few days so that this is more clear. Meanwhile, if you want to update your API wrapper with the allowable invoice statuses, the above list is exhaustive.

Thanks again for pointing this out, and thereby helping the community!


Hello again! We’ve now updated the documentation for Invoices and Estimates to enumerate the full list of status possibilities.

I hope that helps you with your integration problems, and indeed I’m sure it will help folk in the future.

Best regards,



I think the documentation needs improving still.

It is not clear which statuses can be set when creating an invoice, nor does it explain that an invoice can’t be created as Paid.

I have the API creating invoices which then need to be manually opened and marked as Sent before they can be ‘explained’. This is rather time consuming and seems unnecessary. It would really help if the documentation not only listed the statuses but actually defined them, their use and limitations.

Specifically, which status should I choose when I create an invoice using the API so that they appear in FreeAgent as ‘Marked as Sent’?