# Change document state Changes the state of an invoice-type document (invoices-type path segment). | From | To | Value in request body | Notes | | :--- | :--- | :--- | :--- | | draft | final | finalized | All types. | | draft | settled | finalized | Only invoice_receipts. | | draft | deleted | deleted | All types. | | final | canceled | canceled | All types. | | settled | canceled | canceled | Only invoice_receipts. | | final | settled | settled | All types except invoice_receipts and receipts. | | settled | final | unsettled | Only credit_notes and debit_notes. | On receipts (payment receipts) the only transition is canceled; canceling a receipt that is already canceled succeeds without change. The request body wrapper key must be the singular of the path type (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, receipt); any other key returns 422 "Invalid root element, expected invoice" (with the expected key name). To cancel, send the reason in message inside the wrapper, e.g. {"invoice": {"state": "canceled", "message": "Document issued by mistake"}}. Without it the API returns 422 "The cancellation reason is a required field". Endpoint: PUT /api/v3/{invoices-type}/{id}/change-state.json Version: 3.1.0 Security: apiKeyAuth ## Path parameters: - `invoices-type` (string, required) The type of the invoice document. receipts (payment receipts) is accepted here; receipts have no create, update, clone or /new (those operations use DocumentTypeInvoiceParam). Enum: "invoices", "invoice_receipts", "simplified_invoices", "credit_notes", "debit_notes", "receipts" - `id` (integer, required) The document ID. Example: 541674 ## Query parameters: - `api_key` (string, required) Your API Key. Example: "YOUR_API_KEY" ## Request fields (application/json): - `invoice` (object, required) - `invoice.state` (string, required) Target state event (e.g. finalized, deleted, canceled, settled, unsettled). Example: "finalized" - `invoice.message` (string) Cancellation reason. Required when state is canceled; if it is missing or empty the API returns 422 with "The cancellation reason is a required field" (text in the account's language). Ignored for the other states. Returned as cancel_reason on the document. Example: "Document issued by mistake" ## Response 200 fields (application/json): - `invoice` (object) Wrapper key matches the singular of the requested invoice type (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, or receipt). - `invoice.id` (integer) Example: 257224047 - `invoice.status` (string) A finalized document is returned as final (the list endpoint returns the same document as sent). Enum: "draft", "final", "settled", "canceled", "second_copy" - `invoice.archived` (boolean) - `invoice.cancel_reason` (string,null) No enforced length limit; stored as a text column (maps to cancel_message). Example: "Test cancellation" - `invoice.type` (string) Example: "Invoice" - `invoice.sequence_number` (string) Example: "23/INVOICEXPRESSDEMO" - `invoice.inverted_sequence_number` (string) Example: "INVOICEXPRESSDEMO/23" - `invoice.sequence_id` (integer) Example: 5259451 - `invoice.date` (string) dd/mm/yyyy Example: "13/05/2026" - `invoice.due_date` (string) dd/mm/yyyy Example: "13/06/2026" - `invoice.reference` (string,null) - `invoice.observations` (string,null) No enforced length limit; stored as a text column. - `invoice.retention` (number,null) - `invoice.permalink` (string) Example: "https://web.invoicexpress.com/documents/abc123" - `invoice.saft_hash` (string) No enforced character limit (text column). Example: "Xbsc" - `invoice.sum` (number) Example: 100 - `invoice.discount` (number) - `invoice.before_taxes` (number) Example: 100 - `invoice.taxes` (number) Example: 23 - `invoice.total` (number) Example: 123 - `invoice.currency` (string) Example: "Euro" - `invoice.client` (object) - `invoice.client.name` (string) Example: "Test Client" - `invoice.items` (array) - `invoice.items.name` (string) Maximum 60 characters. Longer values are rejected with 422 ("Code for the item is too long"). Example: "Test Item" - `invoice.items.description` (string,null) Maximum 200 characters and at most 20 lines. Longer values are rejected with 422. - `invoice.items.unit_price` (string) Example: "100.0" - `invoice.items.unit` (string) Must be one of a fixed set of supported unit values, not a length-limited free-text field. Example: "service" - `invoice.items.quantity` (string) Example: "1.0" - `invoice.items.tax` (object) - `invoice.items.tax.name` (string) 255-character limit is the database column default; only presence and uniqueness are validated. Example: "IVA23" - `invoice.items.tax.value` (number) Example: 23 - `invoice.items.subtotal` (number) Example: 100 - `invoice.items.tax_amount` (number) Example: 23 - `invoice.items.discount_amount` (number) - `invoice.atcud` (string) Example: "N/D" ## Response 401 fields (application/json): - `errors` (array) Example: [{"error":"Authentication Error"}] - `errors.error` (string) ## Response 404 fields (application/json): - `errors` (array) Example: [{"error":"Resource not found"}] - `errors.error` (string) ## Response 422 fields (application/json): - `errors` (array) Example: [{"error":"The cancellation reason is a required field"}] - `errors.error` (string)