422 error when trying to update an invoice

1

Hi,

I’ve added some categories to our Freeagent account and I’m now trying to apply them to existing invoices through the API. To do this I’m using the update invoice api, i.e. doing a Put to the invoice url, example:

https://api.freeagent.com/v2/invoices/21077539

I’m trying to update the invoice_items of the url with a copy of the original invoice items, but with a category added in to relevant items (I can work this out based on the item text).

When I try to do a post with the updated invoice items I get error 422 either telling me that attributes of the invoice item are locked, or if I remove them that they are missing (e.g. description can’t be blank)

E.g. for this update object:

“{“invoice”:{“invoice_items”:[{“category”:“https://api.freeagent.com/v2/categories/002",“url”:“https://api.freeagent.com/v2/invoice_items/44963981”,“description”:"Taxi for Email subscription to Essential plan from 03 Jul 2017 05:44:02 to 03 Aug 2017 05:44:02”}]}}”

I get this response:

“{“errors”:[{“message”:“invoice_items.description is locked and cannot be changed”},{“message”:“invoice_items.item_type is locked and cannot be changed”},{“message”:“invoice_items.invoice_id is locked and cannot be changed”},{“message”:“invoice_items contain errors”}]}”

We can go through and manually change the category on all of these items but it will take up an enormous amount of time - surely it should be possible to do the same thing through the API?

Any help much appreciated!

2

Hi @will.lahr,

It looks like the invoice you’re attempting to edit is in a Sent state and therefore locked. The solution would be to mark it back to draft, make the required changes and then mark it as Sent again. You should be able to do this via the API; see “Mark invoice as draft” in the Invoices section of the docs

For this particular invoice (#21077539) however, it’d be a bit more complicated due to the fact that it’s been paid. You’d have to remove the payment from the invoice, mark it as draft, make the required changes, mark it as sent again and then add the payment again. This would probably be easier to do from the web UI rather than via the API.

By the way, I had a quick look at this invoice from behind the scenes here, and the invoice item has this category (002) already.

Hope this helps…let us know how you get on!

3

Thanks for getting back to me on this.

Firstly we have hundreds of these that need updating, so doing it through the web interface is not ideal, secondly can you explain why it can be done in the web interface without having to make the invoice a draft but not through the API - While I understand why invoices enter locked periods, have payment status, etc, I can’t see why re-categorising something should be prevented by any of this.

Is it possible to use the invoice item url to update the category rather than the invoice URL - or something like that?

4

OK, I can see that this isn’t really feasible if you’ve got hundreds of them!

FreeAgent prevents any change to an invoice (or it’s invoice items) if the invoice is locked. This is a precautionary measure to ensure that the accounts and underlying ledger entries remain in a valid state.

The workflow for using the API must mirror the flow for using the web UI. For your scenario it will involve a number of requests but it’s still possible. I’ve outlined the steps for you here, with links to the relevant pages in the API docs.

  1. Delete the bank transaction explanation on the invoice.
  2. Mark the invoice as draft.
  3. Update the invoice with the required attributes in the invoice_items field.
  4. Mark the invoice as sent.
  5. Create a new bank transaction explanation for the payment of the invoice.