# Update Guide Updates a guide of the specified type. The wrapper key must match the path segment (shipping, transport or devolution). The same rules as on create apply: loaded_at (not in the past) and at least one item are required, and Portuguese accounts must send complete address_from and address_to. The item list replaces the existing items. Guides that are sent, settled, deleted, canceled or second copies can no longer be edited. Endpoint: PUT /api/v3/{guides-type}/{id} Version: 3.1.0 Security: apiKeyAuth ## Path parameters: - `guides-type` (string, required) The type of the guide document. Enum: "shippings", "transports", "devolutions" - `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 (create only). Accepted here at the top level or inside the wrapper; a repeated value returns the guide already created with it instead of creating a new one. Example: "order-10045" - `transport` (object, required) - `transport.date` (string) Example: "2026-07-13" - `transport.due_date` (string) Example: "2026-07-13" - `transport.loaded_at` (string, required) Load date and time. Required, and must not be in the past; otherwise the API returns 422 Load date must be on or after . Example: "2026-07-13 13:07:00" - `transport.license_plate` (string) Example: "00-AA-00" - `transport.load_site` (string) Loading place (foreign accounts). Example: "Warehouse A" - `transport.delivery_site` (string) Delivery place (foreign accounts). Example: "Client store" - `transport.address_from` (object) Structured address. Used only by Portuguese accounts, where it is required with all four fields filled in; foreign accounts ignore it and use load_site / delivery_site instead. - `transport.address_from.detail` (string, required) Street address. Line breaks are re-inserted roughly every 35 characters before storing. Example: "123 Loading Street" - `transport.address_from.city` (string, required) Example: "Lisbon" - `transport.address_from.postal_code` (string, required) Example: "1000-001" - `transport.address_from.country` (string, required) English country name, matched against the name of the countries list returned by GET /api/v3/{guides-type}/new. An unknown name falls back to Portugal. Example: "Portugal" - `transport.address_to` (object) Structured address. Used only by Portuguese accounts, where it is required with all four fields filled in; foreign accounts ignore it and use load_site / delivery_site instead. - `transport.reference` (string) Example: "PO-1234" - `transport.observations` (string) No enforced length limit; stored as a text column. Example: "Fragile goods" - `transport.sequence_id` (integer) Id of the sequence (series) to issue the guide in. The account's default sequence is used when omitted. Example: 5259467 - `transport.manual_sequence_number` (string) Example: "001" - `transport.tax_exemption` (string) AT tax exemption code (e.g. M01). Example: "M01" - `transport.retention` (number) Withholding tax rate (percentage). Only applied when it matches an active retention base. - `transport.global_discount` (object,null) Document-level discount. Send null to remove an existing discount. - `transport.global_discount.value_type` (string) Enum: "percentage", "absolute" - `transport.global_discount.value` (number) Example: 10 - `transport.currency_code` (string) Only applied when the account's plan includes multi-currency. Example: "EUR" - `transport.rate` (number) Example: 1 - `transport.client_id` (integer) Id of an existing client. Alternative to client.id. Example: 456 - `transport.client` (object) Resolved by id first, then by name / code; a client that does not exist is created. - `transport.client.id` (integer) Example: 456 - `transport.client.name` (string) Example: "John Doe" - `transport.client.code` (string) Example: "C001" - `transport.client.email` (string) Example: "john@example.com" - `transport.client.fiscal_id` (string) Example: "987654321" - `transport.client.address` (string) Example: "456 Client Street" - `transport.client.country` (string) Example: "Portugal" - `transport.items` (array, required) At least one item is required. - `transport.items.description` (string) Example: "Product description" - `transport.items.unit_price` (number) Example: 100 - `transport.items.unit` (string) Example: "unit" - `transport.items.quantity` (number) Example: 2 - `transport.items.discount` (number) - `transport.items.tax` (object) ## Response 200 fields (application/json): - `transport` (object) Wrapper key matches the singular of the requested guide type (transport, shipping, or devolution). - `transport.id` (integer) Example: 263315060 - `transport.status` (string) Example: "draft" - `transport.archived` (boolean) - `transport.type` (string) Example: "Transport" - `transport.sequence_number` (string) Example: "draft" - `transport.inverted_sequence_number` (string) Example: "draft" - `transport.sequence_id` (integer,null) Example: 5259467 - `transport.atcud` (string) Example: "N/A" - `transport.saft_hash` (string) Only present once the guide has been finalized — absent while it is still a draft. Example: "vaDf" - `transport.tax_exemption` (string) 255-character database column default (column tax_exemption_code); effectively an enum of AT exemption codes. Example: "M01" - `transport.date` (string) Example: "2026-07-13" - `transport.due_date` (string) Example: "2026-07-13" - `transport.reference` (string,null) - `transport.observations` (string,null) No enforced length limit (text column). - `transport.token` (string) Example: "263315060c9d7840b5909668386f4a9c93d4b3c4b98ab064e" - `transport.permalink` (string) Example: "https://web.invoicexpress.com/documents/263315060c9d7840b5909668386f4a9c93d4b3c4b98ab064e?language=pt" - `transport.retention` (number) - `transport.global_discount` (object,null) Document-level discount, or null when there is none. - `transport.global_discount.value_type` (string) Enum: "percentage", "absolute" - `transport.global_discount.value` (number) Example: 10 - `transport.loaded_at` (string) Example: "2026-07-13 13:07:00" - `transport.license_plate` (string,null) 255-character DB default; not explicitly validated. - `transport.at_doc_code_id` (string,null) Read-only — written by the AT gateway when the guide is registered, never accepted from callers. 255-character DB default. - `transport.address_from` (object) Returned for Portuguese accounts. Accounts that are not Portuguese get load_site and delivery_site instead of address_from and address_to. - `transport.address_from.detail` (string) 255-character DB default on the Address model (a string column). The API re-inserts line breaks roughly every 35 characters before storing, so a value close to 255 can overflow the column — stay well under the limit. Example: "123 Loading Street" - `transport.address_from.postal_code` (string) 255-character DB default. Example: "1000-001" - `transport.address_from.city` (string) 255-character DB default. Example: "Lisbon" - `transport.address_from.country` (string) Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal. 255-character DB default. Example: "Portugal" - `transport.address_to` (object) - `transport.load_site` (string,null) Free-text load site. Returned instead of address_from for accounts that are not Portuguese (simple address model). No enforced length limit (text column). Example: "123 Loading Street, Lisbon" - `transport.delivery_site` (string,null) Free-text delivery site. Returned instead of address_to for accounts that are not Portuguese (simple address model). No enforced length limit (text column). Example: "456 Delivery Street, Porto" - `transport.owner_invoice_id` (integer,null) - `transport.raw_owner_invoice` (string) Conditional — only present when set. Reference to an original document issued outside InvoiceXpress (isolated credit/debit notes), in the form " /". - `transport.currency` (object,null) Document currency when one was set (multi-currency plans); null otherwise. - `transport.currency.name` (string) Example: "US Dollar" - `transport.currency.code` (string) Example: "USD" - `transport.currency.symbol` (string) Example: "$" - `transport.auto_add_related_document` (boolean) - `transport.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. - `transport.digital_signed` (boolean) Conditional — never present on API-key requests. Only returned to the InvoiceXpress web app; whether the document PDF is digitally signed. - `transport.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. - `transport.account` (object) - `transport.account.organization_name` (string) Example: "invoicexpress" - `transport.account.address` (object) - `transport.account.address.detail` (string) Example: "Avenida Duque D'Avila, Saldanha" - `transport.account.address.postal_code` (string) Example: "1500-555" - `transport.account.address.city` (string) Example: "Lisbon" - `transport.account.address.country` (string) Example: "Portugal" - `transport.account.address.translated_country` (string) Country name in the request language. Example: "Portugal" - `transport.account.email` (string,null) Example: "info@mycompany.com" - `transport.account.phone` (string,null) - `transport.account.phone_country_code` (string) International calling code for the phone/mobile number (e.g. +351); empty string when unset. - `transport.account.phone_indicative_printed` (boolean) Whether the document PDF prints phone behind phone_country_code. - `transport.account.website` (string,null) - `transport.account.footer` (string,null) Document footer text — the document series' configured footer when set, otherwise the account's invoice footer. - `transport.account.fiscal_id` (string) Example: "999999990" - `transport.account.logo` (string) - `transport.account.bank_data` (array) - `transport.client` (object) - `transport.client.phone` (string) Empty string when unset. Example: "210000000" - `transport.client.mobile` (string) Empty string when unset. Example: "910000000" - `transport.client.mobile_country_code` (string) International calling code for the phone/mobile number (e.g. +351); empty string when unset. - `transport.client.fiscal_id` (string) 255-character DB default; not explicitly validated. Example: "987654321" - `transport.client.translated_country` (string) Client's fiscal country name in the request language. Example: "Portugal" - `transport.items` (array) - `transport.items.name` (string) Maximum 60 characters. Longer values are rejected with 422 ("Code for the item is too long"). Example: "Product Name" - `transport.items.description` (string) Maximum 200 characters and at most 20 lines. Longer values are rejected with 422. Example: "Product description" - `transport.items.unit_price` (number) Example: 100 - `transport.items.unit` (string) Must be one of a fixed set of supported unit values, not a free-length string. Example: "piece" - `transport.items.quantity` (number) Example: 2 - `transport.items.tax` (object) - `transport.items.discount` (number) - `transport.items.subtotal` (number) Example: 180 - `transport.items.tax_amount` (number) Example: 41.4 - `transport.items.discount_amount` (number) - `transport.items.total` (number) Example: 221.4 - `transport.summary` (object) - `transport.summary.sum` (number) Example: 200 - `transport.summary.before_taxes` (number) Example: 180 - `transport.summary.taxes` (number) Example: 41.4 - `transport.summary.currency` (object) - `transport.summary.pay_progress` (number) - `transport.summary.to_pay` (number) Example: 221.4 - `transport.summary.total_paid` (number) - `transport.summary.taxes_breakdown` (array) - `transport.summary.taxes_breakdown.category` (string) Example: "IVA23" - `transport.summary.taxes_breakdown.items_value` (number) Example: 180 - `transport.summary.taxes_breakdown.tax_value` (number) Example: 41.4 - `transport.summary.total_currency_rate` (number) - `transport.summary.rate` (number) Example: 1 ## 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 transport element provided"},{"error":"No items element provided"},{"error":"No address_from element provided"}] - `errors.error` (string) ## Response 422 fields (application/json): - `errors` (array) Example: [{"error":"No transport element provided"},{"error":"No items element provided"},{"error":"No address_from element provided"}] - `errors.error` (string) ## Response 500 fields (application/json): - `errors` (array) Example: [{"error":"An unexpected error occurred"}] - `errors.error` (string)