# Update Invoice-type Document Updates a document of the specified invoice type and returns it. The id must belong to a document of that type. The request body wrapper key must be the singular of the path segment (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note). The body accepts the same fields as create, and items must again contain at least one item: the item list sent replaces the stored one. Documents in status sent, settled, deleted, canceled, accepted, refused or second_copy cannot be changed (422 "Document has been finalized so can't be changed anymore"). Endpoint: PUT /api/v3/{invoices-type}/{id} Version: 3.1.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" - `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): - `proprietary_uid` (string) Your own idempotency identifier for the document. Accepted here at the top level or inside the wrapper; a repeated value returns the document already created with it instead of creating a new one. Example: "order-10045" - `invoice` (object) - `invoice.date` (string, required) Example: "2024-01-15" - `invoice.due_date` (string) Defaults to date when omitted or blank. Example: "2024-02-15" - `invoice.reference` (string) Example: "PO-1234" - `invoice.observations` (string) No enforced length limit; stored as a text column. Example: "Payment terms: 30 days" - `invoice.sequence_id` (integer) Id of the sequence (series) to issue the document in. The account's default sequence is used when omitted. Example: 5259451 - `invoice.manual_sequence_number` (string) Example: "001" - `invoice.tax_exemption` (string) AT tax exemption code (e.g. M01). M00 clears a previously set exemption. Ignored when the account does not use tax exemption reasons or the code is unknown. Example: "M01" - `invoice.tax_exemption_code` (string) Stored exemption code column; prefer tax_exemption. Example: "M01" - `invoice.tax_exemption_reason` (string) Alias of tax_exemption, used only when tax_exemption is blank. Example: "M01" - `invoice.retention` (number) Withholding tax rate (percentage). Only applied when it matches an active retention base; any other value is ignored. Example: 25 - `invoice.global_discount` (object,null) Document-level discount. Send null (or a value of 0) to remove an existing discount; omit the key to leave it unchanged. - `invoice.global_discount.value_type` (string) Enum: "percentage", "absolute" - `invoice.global_discount.value` (number) Example: 10 - `invoice.currency_code` (string) Currency code (e.g. USD). Only applied when the account's plan includes multi-currency; unknown codes are ignored. Example: "USD" - `invoice.rate` (number) Exchange rate to the account currency. Example: 1.08 - `invoice.owner_invoice_id` (integer) Id of the invoice this credit/debit note corrects. Example: 541673 - `invoice.raw_owner_invoice` (any) Reference to an original document issued outside InvoiceXpress, for a credit/debit note with no owner_invoice_id. Either a string " /" (max 60 characters) or an object with the three parts. - `invoice.client_id` (integer) Id of an existing client. Alternative to client.id. Example: 456 - `invoice.mb_reference` (boolean) Generate a Multibanco payment reference for the document. - `invoice.auto_add_related_document` (boolean) Overwritten by the server. Set to false unless mb_reference is true; with mb_reference true and the account's "auto-send invoice from estimate" setting on, it is forced to true. - `invoice.proprietary_uid` (string) Same as the top-level proprietary_uid. Example: "order-10045" - `invoice.client` (object) Optional. When omitted, the document is issued to Consumidor Final (credit and debit notes take the client of the invoice in owner_invoice_id). - `invoice.client.id` (integer) If provided and it matches an existing client on the account, that client is used and name/email/fiscal_id/address are ignored; otherwise name is used to find or create the client. Example: 456 - `invoice.client.name` (string) Example: "John Doe" - `invoice.client.email` (string) Example: "john@example.com" - `invoice.client.fiscal_id` (string) 255-character limit is the database column default, not an explicit validation. Example: "987654321" - `invoice.client.address` (string) Street address as a flat string (not a nested object). No enforced length limit; stored as a text column. Example: "456 Client Street" - `invoice.client.postal_code` (string) 255-character limit is the database column default, not an explicit validation. Example: "2000-002" - `invoice.client.city` (string) 255-character limit is the database column default, not an explicit validation. Example: "Porto" - `invoice.client.country` (string) Fiscal country of the client. 255-character limit is the database column default, not an explicit validation. Example: "Portugal" - `invoice.client.address_country` (string) Country of the postal address, when different from the fiscal country; takes priority over country for the address. Example: "Portugal" - `invoice.items` (array, required) - `invoice.items.name` (string) Maximum 60 characters. Longer values are rejected with 422 ("Code for the item is too long"). Example: "Product Name" - `invoice.items.description` (string) Maximum 200 characters and at most 20 lines. Longer values are rejected with 422. Example: "Product description" - `invoice.items.unit_price` (number) Example: 100 - `invoice.items.unit` (string) Must be one of a fixed set of supported unit values, not a length-limited free-text field. Example: "piece" - `invoice.items.quantity` (string) Example: "2.00" - `invoice.items.tax` (object) - `invoice.items.tax.id` (integer) Example: 1 - `invoice.items.tax.name` (string) 255-character limit is the database column default; only presence and uniqueness are validated. Example: "IVA23" - `invoice.items.discount` (number) Example: 10 - `invoice.items.subtotal` (number) Example: 180 - `invoice.items.tax_amount` (number) Example: 41.4 - `invoice.items.discount_amount` (number) Example: 20 - `invoice.items.total` (number) Example: 221.4 - `invoice.items.retention` (number) ## Response 200 fields (application/json): - `invoice` (object) Wrapper key matches the singular of the requested invoice type (invoice, invoice_receipt, simplified_invoice, credit_note, or debit_note). - `invoice.id` (integer) Example: 541674 - `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.cancel_reason` (string) No enforced length limit; stored as a text column (maps to cancel_message). Example: "document was duplicated" - `invoice.archived` (boolean) - `invoice.type` (string) Example: "Invoice" - `invoice.sequence_number` (string) Example: "2024/001" - `invoice.inverted_sequence_number` (string) Example: "001/2024" - `invoice.sequence_id` (integer,null) Example: 123 - `invoice.owner_invoice_id` (integer,null) Example: 541673 - `invoice.atcud` (string) Example: "ATCUD123456" - `invoice.saft_hash` (string) Only present once the document has been finalized — absent while it is still a draft. Example: "1234" - `invoice.tax_exemption` (string) 255-character database column default (column tax_exemption_code); effectively an enum of AT exemption codes. Example: "M01" - `invoice.date` (string) Example: "2024-01-15" - `invoice.due_date` (string) Example: "2024-02-15" - `invoice.reference` (string,null) Example: "REF001" - `invoice.observations` (string,null) No enforced length limit; stored as a text column. Example: "Payment terms: 30 days" - `invoice.token` (string) Example: "541674bbfcdd182143fe2747524df08ab1367ef8255010" - `invoice.permalink` (string) Example: "https://web.invoicexpress.com/documents/541674bbfcdd182143fe2747524df08ab1367ef8255010?language=pt" - `invoice.retention` (number) - `invoice.global_discount` (object,null) Document-level discount, or null when there is none. - `invoice.global_discount.value_type` (string) Enum: "percentage", "absolute" - `invoice.global_discount.value` (number) Example: 10 - `invoice.raw_owner_invoice` (string) Conditional — only present when set. Reference to an original document issued outside InvoiceXpress (isolated credit/debit notes), in the form " /". - `invoice.currency` (object,null) Document currency when one was set (multi-currency plans); null otherwise. - `invoice.currency.name` (string) Example: "US Dollar" - `invoice.currency.code` (string) Example: "USD" - `invoice.currency.symbol` (string) Example: "$" - `invoice.auto_add_related_document` (boolean) - `invoice.qr_code` (string) Conditional — never present on API-key requests. Only returned to the InvoiceXpress web app, for non-draft documents with a real ATCUD once the QR code image has been generated. Public URL of the QR code image. - `invoice.digital_signed` (boolean) Conditional — never present on API-key requests. Only returned to the InvoiceXpress web app; whether the document PDF is digitally signed. - `invoice.include_payment_reference` (boolean) Conditional — never present on API-key requests. Only returned to the InvoiceXpress web app for draft (or deleted) documents of a type that supports a Multibanco reference, when the plan includes MB, an MB provider is configured and the document has no MB reference yet. Reflects the account's "add payment reference by default" preference. - `invoice.account` (object) - `invoice.account.organization_name` (string) Example: "My Company Ltd" - `invoice.account.address` (object) - `invoice.account.address.detail` (string) Example: "123 Main Street" - `invoice.account.address.postal_code` (string) Example: "1000-001" - `invoice.account.address.city` (string) Example: "Lisbon" - `invoice.account.address.country` (string) Example: "Portugal" - `invoice.account.address.translated_country` (string) Country name in the request language. Example: "Portugal" - `invoice.account.email` (string,null) Example: "info@mycompany.com" - `invoice.account.phone` (string,null) - `invoice.account.phone_country_code` (string) International calling code for the phone/mobile number (e.g. +351); empty string when unset. - `invoice.account.phone_indicative_printed` (boolean) Whether the document PDF prints phone behind phone_country_code. - `invoice.account.website` (string,null) - `invoice.account.footer` (string,null) Document footer text — the document series' configured footer when set, otherwise the account's invoice footer. - `invoice.account.fiscal_id` (string) Example: "123456789" - `invoice.account.logo` (string) Example: "https://example.com/logo.png" - `invoice.account.bank_data` (array) - `invoice.client` (object) - `invoice.client.phone` (string) Empty string when unset. Example: "210000000" - `invoice.client.mobile` (string) Empty string when unset. Example: "910000000" - `invoice.client.mobile_country_code` (string) International calling code for the phone/mobile number (e.g. +351); empty string when unset. - `invoice.client.fiscal_id` (string) 255-character limit is the database column default, not an explicit validation. Example: "987654321" - `invoice.client.translated_country` (string) Client's fiscal country name in the request language. Example: "Portugal" - `invoice.items` (array) - `invoice.items.name` (string) Maximum 60 characters. Longer values are rejected with 422 ("Code for the item is too long"). Example: "Product Name" - `invoice.items.description` (string) Maximum 200 characters and at most 20 lines. Longer values are rejected with 422. Example: "Product description" - `invoice.items.unit_price` (number) Example: 100 - `invoice.items.unit` (string) Must be one of a fixed set of supported unit values, not a length-limited free-text field. Example: "piece" - `invoice.items.quantity` (number) Example: 2 - `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.discount` (number) Example: 10 - `invoice.items.subtotal` (number) Example: 180 - `invoice.items.tax_amount` (number) Example: 41.4 - `invoice.items.discount_amount` (number) Example: 20 - `invoice.items.total` (number) Example: 221.4 - `invoice.summary` (object) - `invoice.summary.sum` (number) Example: 200 - `invoice.summary.before_taxes` (number) Example: 180 - `invoice.summary.taxes` (number) Example: 41.4 - `invoice.summary.currency` (object) - `invoice.summary.pay_progress` (number) - `invoice.summary.to_pay` (number) - `invoice.summary.total_paid` (number) - `invoice.summary.taxes_breakdown` (array) - `invoice.summary.taxes_breakdown.category` (string) Example: "IVA23" - `invoice.summary.taxes_breakdown.items_value` (number) Example: 180 - `invoice.summary.taxes_breakdown.tax_value` (number) Example: 41.4 - `invoice.summary.total_currency_rate` (number) - `invoice.summary.rate` (number) Example: 1 - `invoice.mb_reference` (object,null) - `invoice.mb_reference.entity` (string) Example: "12345" ## 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 409 fields (application/json): - `errors` (array) Example: [{"error":"No invoice element provided"},{"error":"No items element provided"}] - `errors.error` (string) ## Response 422 fields (application/json): - `errors` (array) Example: [{"error":"No invoice element provided"},{"error":"No items element provided"}] - `errors.error` (string) ## Response 500 fields (application/json): - `errors` (array) Example: [{"error":"An unexpected error occurred"}] - `errors.error` (string)