invoices.change-state

Changes the state of an invoice.

Possible state transitions:

draft to final – finalized
final to second copy – second_copy
final or second copy to canceled – canceled
final or second copy to settled – settled
settled to final – unsettled

Any other transitions will fail.

When canceling an invoice you must specify a reason.

You call this method by submitting a HTTP PUT request to the following URL :

https://:screen-name.invoicexpress.net/invoice/:invoice-id/change-state.xml

Example xml to be submitted with the updated invoice data:

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
 <state>canceled</state>
 <message>Canceled due to amount of money</message>
</invoice>

<invoice>
 <state>finalized</state>
</invoice>

Parameters

Parameters are the data you will pass with the call.

api_key

Your secret identifier. You find your API Key under Account Overview in the Account section.
Rules: Required

invoice-id

Id of the invoice to change state.
Rules: Required

state

State which the invoice will be changed to. Options are:

finalized
second_copy
canceled
settled
unsettled

Rules: Required

message

Reason for cancelling the invoice.
Rules: Required when state is “canceled”, otherwise ignored.

Return Values

This is the result that will be passed back to you.

Success

The requested invoice is passed back in the response.

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
 <id>1024</id>
 <type>Invoice</type>
 <sequence_number>1/XXX</sequence_number>
 <state>canceled</state>
 <message>Canceled due to amount of money</message>
</invoice>

Error

HTTP: 401 Access denied
The API Key parameter is missing or is incorrectly entered.

HTTP: 404 Not Found
No invoice matches the :invoice-id supplied.

HTTP: 422 Unprocessable Entity
Some of the parameters were incorrect.

Possible errors:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>No content type or wrongly specified.</error>
</errors>

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>Invalid state</error>
</errors>

<?xml version="1.0" encoding="UTF-8"?>
<errors>
 <error>Cancel message can't be blank</error>
</errors>