---
title: "Update Guide"
method: PUT
path: "/{guides-type}/{document-id}.json"
tags: ["Guides"]
---

# Update Guide

`PUT /{guides-type}/{document-id}.json`

Updates a shipping, transport or devolution.

## Path parameters

- `guides-type` 'shippings' | 'transports' | 'devolutions', required
- `document-id` integer, required

## Query parameters

- `api_key` string, required

## Request body

- GuideCreateRequest
  - `shipping` object, required
    - `date` string, required — dd/mm/yyyy
    - `due_date` string, required — dd/mm/yyyy
    - `loaded_at` string, required — dd/mm/yyyy HH:mm:ss
    - `license_plate` string — 255-character limit is the database column default, not an explicit business rule.
    - `address_from` object, required
      - `detail` string, required — 255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit.
      - `city` string, required — 255-character limit is the database column default on the Address model, not an explicit business rule.
      - `postal_code` string, required — 255-character limit is the database column default on the Address model, not an explicit business rule.
      - `country` string, required — Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal.
    - `address_to` object, required
      - `detail` string, required — 255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit.
      - `city` string, required — 255-character limit is the database column default on the Address model, not an explicit business rule.
      - `postal_code` string, required — 255-character limit is the database column default on the Address model, not an explicit business rule.
      - `country` string, required — Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal.
    - `reference` string
    - `observations` string — No enforced character limit (text column).
    - `retention` string
    - `tax_exemption` string
    - `sequence_id` string
    - `manual_sequence_number` string — 255-character limit is the database column default, not an explicit business rule.
    - `client` object, required — To identify an existing client, send `id`, `code`, or `name` — not all three are required. Resolution priority: if `id` is sent and matches a client on the account, that client is used and `name`/`code` are ignored. Without `id`, if `code` matches an existing client, that client is used and `name` is not needed. Without an `id`/`code` match, `name` is used to find or create the client. Creating a brand-new client (no `id`/`code` match) still requires `name`; `code` is always optional and is never generated automatically by InvoiceXpress.
      - `id` integer — Internal client ID. Preferred way to identify an existing client — see the object description.
      - `name` string
      - `code` string — 255-character limit is the database column default, not an explicit business rule.
      - `email` string
      - `address` string — No enforced character limit (text column).
      - `city` string — 255-character limit is the database column default, not an explicit business rule.
      - `postal_code` string — 255-character limit is the database column default, not an explicit business rule.
      - `country` string — 255-character limit is the database column default, not an explicit business rule.
      - `fiscal_id` string — 255-character limit is the database column default, not an explicit business rule.
      - `website` string
      - `phone` string
      - `fax` string
      - `observations` string — No enforced character limit (text column).
    - `items` object[], required
      - `name` string, required — Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters.
      - `description` string, required — Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters.
      - `unit_price` string, required
      - `quantity` string, required
      - `unit` string — Restricted to a fixed set of unit values rather than length-limited free text.
      - `discount` string
      - `tax` object
        - `name` string
    - `tax_exemption_reason` string — Validated at 210 characters by the document model, below the 255-character database column limit.
    - `load_site` string — No enforced character limit (text column).
    - `delivery_site` string — No enforced character limit (text column).

## Response `200`

SUCCESS 

#### Possible values for field atcud:

* ABCD1234-1 (or similar) - Unique document identifier to the Tax Authority, when the sequence is registered.
* N/D - The document's sequence is relevant for ATCUD but is not registered in the Tax Authority.
* N/A - The document's sequence is not relevant for ATCUD and is not registered in the Tax Authority.

- GuideGetResponse
  - `shipping` object — Wrapper key matches the singular of the requested guide type — `shipping`, `transport` or `devolution`. Shown here as "shipping".
    - `id` integer
    - `status` string
    - `archived` boolean
    - `type` string
    - `sequence_number` string
    - `inverted_sequence_number` string
    - `atcud` string
    - `date` string
    - `due_date` string — dd/mm/yyyy
    - `reference` string, nullable
    - `observations` string, nullable — No enforced character limit (text column).
    - `retention` string, nullable
    - `loaded_at` string — dd/mm/yyyy HH:mm:ss. Note the list endpoint returns this same field as date-only (dd/mm/yyyy).
    - `license_plate` string, nullable — 255-character limit is the database column default, not an explicit business rule.
    - `permalink` string
    - `saft_hash` string — No enforced character limit (text column).
    - `sum` number
    - `discount` number
    - `before_taxes` number
    - `taxes` number
    - `total` number
    - `currency` string
    - `address_from` object
      - `country` string — Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal.
      - `postal_code` string — 255-character limit is the database column default on the Address model, not an explicit business rule.
      - `detail` string — 255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit.
      - `city` string — 255-character limit is the database column default on the Address model, not an explicit business rule.
    - `address_to` object
      - `country` string — Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal.
      - `postal_code` string — 255-character limit is the database column default on the Address model, not an explicit business rule.
      - `detail` string — 255-character limit is the database column default on the Address model, not an explicit business rule. Note the API re-inserts line breaks roughly every 35 characters before storing, so an input close to 255 characters can overflow the column — keep well under the limit.
      - `city` string — 255-character limit is the database column default on the Address model, not an explicit business rule.
    - `client` object
      - `id` integer
      - `name` string
      - `country` string — 255-character limit is the database column default, not an explicit business rule.
    - `items` object[]
      - `name` string — Maximum 60 characters. V3 rejects a longer name with HTTP 422; V2 accepts the request and silently truncates the stored value to 60 characters.
      - `description` string, nullable — Maximum 200 characters and 20 lines. V3 rejects a longer description with HTTP 422; V2 accepts the request and silently truncates the stored value to 200 characters.
      - `unit_price` string
      - `unit` string, nullable — Restricted to a fixed set of unit values rather than length-limited free text.
      - `quantity` string
      - `tax` object
        - `id` integer
        - `name` string
        - `value` number
      - `discount` number
      - `subtotal` number
      - `tax_amount` number
      - `discount_amount` number
      - `total` number
    - `sequence_id` integer, nullable
    - `tax_exemption` string
    - `at_doc_code_id` string, nullable — Read-only. Written only by the AT gateway and never accepted on input. The 255-character limit is the database column default, not an explicit business rule.

## Other responses

- `401` — ACCESS DENIED
- `404` — NOT FOUND
- `422` — UNPROCESSABLE ENTITY

---

[API](https://skmtc.dev/invoicexpress/apis/invoicexpress-api.md) · [All operations](https://skmtc.dev/invoicexpress/apis/invoicexpress-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/invoicexpress/invoicexpress-api/revisions/5b82d4eb0d9f/schema)