# Change Invoice State

Changes the state of invoice documents.

| From | To | State on Request Body | Notes |
| :--- | :--- | :--- | :--- |
| draft | final | finalized | All documents except invoice_receipt. |
| draft | settled | finalized | Only invoice_receipt. |
| draft | deleted | deleted | All documents. |
| final | canceled | canceled | All documents. Requires message (the cancellation reason). |
| settled | canceled | canceled | Only invoice_receipt. Requires message. |
| final | settled | settled | invoice, simplified_invoice, credit_note and debit_note. Not available for invoice_receipt. |
| settled | final | unsettled | Only credit_note and debit_note. |

> Note: An invoice or simplified_invoice settled with settled cannot be returned to final or canceled through the API.

Endpoint: PUT /{invoices-type}/{document-id}/change-state.json
Version: 2.0.0
Security: apiKeyAuth

## Path parameters:

  - `invoices-type` (string, required)
    The type of the invoice document.
    Enum: "invoices", "invoice_receipts", "simplified_invoices", "credit_notes", "debit_notes"

  - `document-id` (integer, required)
    The ID of the document.
    Example: 1050

## Query parameters:

  - `api_key` (string, required)
    Your API Key.
    Example: "YOUR_API_KEY"

## Request fields (application/json):

  - `invoice` (object, required)

  - `invoice.state` (string, required)
    Enum: "finalized", "deleted", "canceled", "settled", "unsettled"

  - `invoice.message` (string)
    Cancellation reason. Required when state is canceled, otherwise the request fails with 422 The cancellation reason is a required field. No enforced character limit. English text shown; the message follows the account language.
    Example: "Wrong value"

## Response 200 fields (application/json):

  - `invoice` (object)

  - `invoice.id` (integer)
    Example: 2137287

  - `invoice.status` (string)
    Example: "final"

  - `invoice.archived` (boolean)

  - `invoice.type` (string)
    Example: "Invoice"

  - `invoice.sequence_number` (string)
    Example: "6/G"

  - `invoice.inverted_sequence_number` (string)
    Example: "G/6"

  - `invoice.atcud` (string)
    Example: "ABCD1234-6"

  - `invoice.sequence_id` (integer,null)
    Example: 12345

  - `invoice.tax_exemption` (string)
    Example: "M01"

  - `invoice.date` (string)
    Example: "04/08/2016"

  - `invoice.due_date` (string)
    Example: "19/08/2016"

  - `invoice.reference` (string,null)
    Example: "ref123"

  - `invoice.observations` (string,null)
    No enforced character limit (text column).
    Example: "Observations"

  - `invoice.retention` (string,null)

  - `invoice.cancel_reason` (string,null)
    Present after the document has been canceled. No enforced character limit (text column).
    Example: "API test cancellation"

  - `invoice.permalink` (string)
    Example: "https://web.invoicexpress.com/documents/..."

  - `invoice.saft_hash` (string)
    Server-generated. No enforced character limit (text column).
    Example: "J4ay"

  - `invoice.sum` (number)
    Example: 24.39

  - `invoice.discount` (number,null)

  - `invoice.before_taxes` (number)
    Example: 24.39

  - `invoice.taxes` (number)
    Example: 5.61

  - `invoice.total` (number)
    Example: 30

  - `invoice.currency` (string)
    Example: "Euro"

  - `invoice.client` (object)
    id and name are always present. The other fields are only returned when they have a value.

  - `invoice.client.name` (string)
    Example: "John Doe"

  - `invoice.client.code` (string)
    Example: "C1"

  - `invoice.client.country` (string)
    Example: "Portugal"

  - `invoice.client.email` (string)
    Example: "john@example.com"

  - `invoice.client.address` (string)
    Example: "Avenida da República"

  - `invoice.client.postal_code` (string)
    Example: "1050-555"

  - `invoice.client.city` (string)
    Example: "Lisboa"

  - `invoice.client.fiscal_id` (string)
    Example: "508025338"

  - `invoice.client.website` (string)
    Example: "www.example.com"

  - `invoice.client.phone` (string)
    Example: "910000000"

  - `invoice.client.fax` (string)
    Example: "210000000"

  - `invoice.client.observations` (string)
    Example: "VIP client"

  - `invoice.items` (array)

  - `invoice.items.description` (string,null)
    Example: "Big Product"

  - `invoice.items.unit_price` (string)
    Example: "100.0"

  - `invoice.items.quantity` (string)
    Example: "1.0"

  - `invoice.items.unit` (string)
    Example: "un"

  - `invoice.items.tax` (object)

  - `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.mb_reference` (object)

  - `invoice.mb_reference.entity` (string)
    Example: "10611"

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.error` (string)
    Example: "Authentication Error"

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.error` (string)
    Example: "Document not found"

## Response 422 fields (application/json):

  - `errors` (array)
    Example: [{"error":"CantHandle: 1 for Invoice"},{"error":"The cancellation reason is a required field"}]

  - `errors.error` (string)