---
title: "🔒 Update sales order V3"
method: PATCH
path: "/api/v3/salesOrders/{id}"
tags: ["SalesOrder"]
---

# 🔒 Update sales order V3

`PATCH /api/v3/salesOrders/{id}`

This endpoint is currently in Beta and available for testing. It may contain bugs, and breaking changes can occur at any time without prior notice. We do not recommend using Beta endpoints in production environments. Should you choose to use it in production, you assume full responsibility for any resulting issues.

This endpoint requires the following scopes: `salesOrder:update`.

Update a sales order.

## Path parameters

- `id` string, required

## Request body

- object — Indicates that the entity has a deviating shipTo address.
  - `documentDate` string, date — Date of the document
  - `documentAddress` object — The recipients postal address of the document
    - `type` 'mrs' | 'mr' | 'company' | 'other' — Type of the recipient
    - `name` string — Name of the recipient
    - `title` string — Title of the recipient
    - `contactPerson` string — Contact person
    - `department` string — Department
    - `subDepartment` string — Sub-department
    - `addressSupplement` string — Address supplement
    - `street` string — Street address
    - `zipCode` string — ZIP Code
    - `city` string — City
    - `state` string — State
    - `country` string — Country
    - `gln` string — Global Location Number
    - `salutation` string — Salutation
    - `email` string — Email address
    - `phone` string — Phone number
    - `fax` string — Fax number
    - `mobile` string — Mobile number
  - `project` object — The project associated with the document. Set to null to remove project association.
    - `id` string, required — ID of the project
  - `internalDesignation` string — Internal designation, might be displayed in the letterhead
  - `bodyIntroduction` string — Introduction text for the body of the document
  - `bodyOutroduction` string — Outroduction text for the body of the document
  - `vatId` string — VAT ID of the business partner
  - `deliveryTerms` string — Delivery terms for the document
  - `internalComment` string — Internal comment for the document
  - `language` string — Language of the document in an ISO-639-1 format.
  - `printSettings` object — Print settings for the document
    - `withoutLetterhead` boolean — If true, the document will be printed without letterhead
    - `withoutProductText` boolean — If true, the document will be printed without product text
  - `editor` object — Editor information
    - `id` string — Editor address ID
  - `tags` object[] — List of tags associated with the document. The passed list replaces the currently associated tags.
    - `title` string, required — Title of the Tag
  - `costCenter` string — Cost center for the document
  - `financials` object
    - `tax` object — Tax properties of the document
      - `taxation` 'domestic' | 'eu' | 'export' | 'exempt' — Taxation of the document, e.g. "domestic" or "eu".
    - `currency` string — Currency of the document, e.g. "EUR" or "USD".
    - `exchangeRate` number, float — Per-document exchange rate, used when the document currency differs from the system base currency. Overrides the rate from the global currency exchange table for this document. A value of 0 means: use the global rate from currency exchange.
  - `preferredWarehouse` object — The preferred warehouse.
    - `id` string — Preferred warehouse ID
  - `sales` object — Sales information
    - `id` string — Sales address ID
  - `deviatingShipToAddress` object
    - `type` 'mrs' | 'mr' | 'company' | 'other' — Type of the recipient
    - `name` string — Name of the recipient
    - `title` string — Title of the recipient
    - `contactPerson` string — Contact person
    - `department` string — Department
    - `subDepartment` string — Sub-department
    - `addressSupplement` string — Address supplement
    - `street` string — Street address
    - `zipCode` string — ZIP Code
    - `city` string — City
    - `state` string — State
    - `country` string — Country
    - `gln` string — Global Location Number
    - `salutation` string — Salutation
    - `email` string — Email address
    - `phone` string — Phone number
    - `fax` string — Fax number
    - `mobile` string — Mobile number
  - `masterReferenceNumber` string — Master reference number for the sales order.
  - `commissionConsignmentWarehouse` object — Commission/consignment warehouse for the sales order. This is used by the commission/consignment module.
    - `id` string

## Response `200`

Update a sales order.

- object
  - `data` object — Sales order document
    - `id` string — ID of the document
    - `documentNumber` string — Document number. For drafts, this will be null.
    - `documentDate` string, date — Main date of the document.
    - `writeProtection` boolean — Indicates if the document is write protected.
    - `customerNumber` string — Customer number of the document.
    - `address` union — Address entity of the document. By default, only the ID is returned. To get the full Address object, use the `include` parameter.
      - object
        - `id` string, required
        - `isDeleted` boolean — Flagged if the entry was deleted.
        - `createdAt` string, date-time, required — Creation timestamp
        - `updatedAt` string, date-time, required — Last update timestamp
      - object
        - `id` string
    - `project` union — Project entity of the document. By default, only the ID is returned. To get the full Project object, use the `include` parameter.
      - object
        - `id` string, required
        - `name` string, required
        - `abbreviation` string, required
      - object
        - `id` string
    - `tags` object[] — Tags assigned to the document. This property is only returned if the `tags` include is used.
      - `id` string — ID of the tag
      - `title` string — Title of the tag
    - `documentAddress` object — The recipients postal address of the document. This is is usually the postal address of the document's address entitiy, (e.g. customer), or is populated based on the preceding document. As this address is persisted on the document level, it can however be modified independently, and does not reflect changes that occurred since the document was created.
      - `name` string, required — Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc.
      - `type` 'mrs' | 'mr' | 'company' | 'other'
      - `title` string
      - `contactPerson` string
      - `department` string
      - `subDepartment` string
      - `addressSupplement` string
      - `street` string
      - `zipCode` string
      - `city` string
      - `state` string
      - `country` string
      - `salutation` string
      - `gln` string
      - `email` string
      - `phone` string
      - `fax` string
      - `mobile` string
    - `internalDesignation` string — Internal designation, might be displayed in the letterhead.
    - `isDocumentSent` boolean — Indicates if the document has been sent to the recipient.
    - `language` string — ISO 639-1 Language of the document.
    - `bodyIntroduction` string — Text displayed on the document before the line items.
    - `bodyOutroduction` string — Text displayed on the document after the line items.
    - `vatId` string — VAT ID of the document.
    - `deliveryTerms` string — Delivery terms of the document.
    - `internalComment` string — Internal comment, does not show up on the document. Intended to be used for company-internal notes.
    - `editor` object
      - `id` string — ID of the user who is responsible for the document.
    - `printSettings` object
      - `withoutLetterhead` boolean — For PDFs or physical documents, hide the letterhead
      - `withoutProductText` boolean — For PDFs or physical documents, hide the product text
    - `activity` object[] — Activity log entries associated with the document. To get activity object, use the `include` parameter.
      - `message` string, required
      - `causer` string, required
      - `causedAt` string, date-time, required
    - `customFields` object[] — Custom fields with their values and metadata
      - `key` string
      - `value` string
      - `label` string
    - `updatedAt` string, date-time
    - `createdAt` string, date-time
    - `financials` object — Financials properties of the document
      - `paymentMethod` object — Payment method of the document. This is a reference to the payment method used for the document.
        - `id` string
      - `paymentTerms` object — Payment terms of the document
        - `paymentTargetDays` integer
        - `paymentTargetDiscount` number, float
        - `paymentTargetDiscountDays` integer
      - `tax` object — Tax properties of the document
        - `taxation` 'domestic' | 'eu' | 'export' | 'exempt' — Taxation of the document, e.g. "domestic" or "eu".
        - `disableTaxNotice` boolean — Indicates if the tax notice should be disabled for this document.
        - `taxRates` object — Tax rates of the document. These values cannot be edited directly via the Xentral UI, and are set based on the tax settings and the delivery or billing region.
          - `standard` number, float
          - `reduced` number, float
      - `currency` string — Currency of the document as an ISO 4217 code, e.g. "EUR" or "USD".
      - `exchangeRate` unknown
    - `totals` object — Totals of the document. These values cannot be set directly, but are calculated based on the line items
      - `net` object — Money
        - `amount` union
          - string
          - number
        - `currency` string — Currency
      - `gross` object — Money
        - `amount` union
          - string
          - number
        - `currency` string — Currency
      - `contributionMargin` number, float — Contribution margin of the document.
    - `offer` object — Offer reference
      - `id` string — ID of the offer
    - `preferredWarehouse` object — Preferred warehouse for the document.
      - `id` string — ID of the preferred warehouse
    - `sales` object — Sales person responsible for the document.
      - `id` string
    - `status` 'draft' | 'released' | 'completed' | 'cancelled' — Status of the document
    - `supplierNumber` unknown
    - `deviatingShipToAddress` object — Represents a postal address with contact information.
      - `name` string, required — Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc.
      - `type` 'mrs' | 'mr' | 'company' | 'other'
      - `title` string
      - `contactPerson` string
      - `department` string
      - `subDepartment` string
      - `addressSupplement` string
      - `street` string
      - `zipCode` string
      - `city` string
      - `state` string
      - `country` string
      - `salutation` string
      - `gln` string
      - `email` string
      - `phone` string
      - `fax` string
      - `mobile` string
    - `isSalesOrderToSupplier` boolean — Indicates if this sales order is a sales order to a supplier.
    - `externalOrderNumber` string — External order number of the sales order, e.g. from a webshop
    - `customerOrderNumber` string — Customer order number of the sales order, e.g. the customer's order number
    - `transactionNumber` string — Transaction number of the sales order, e.g. for payment processing. Please not that this value can currently not be edited via the Xentral UI.
    - `externalOrderId` string — External order ID of the sales order, e.g. from a webshop or external system. This is not the same as the external order number. The external order ID is often used for integration purposes, and is typically a technical identifier from a upstream system.
    - `desiredDeliveryDate` string, date — Desired delivery date of the sales order. This is the date when the customer expects the order to be delivered.
    - `desiredDeliveryDateAsCalendarWeek` boolean — Indicates if the desired delivery date is expressed as a calendar week. If true, the `desiredDeliveryDate` should be interpreted as the start of the calendar week.
    - `earliestFulfillmentDate` string, date — Earliest fulfillment date of the sales order. This is the date when the order can be fulfilled at the earliest.
    - `reservationDate` string, date — Reservation date of the sales order. Before this date (if set), the order is not considered for stock reservations.
    - `commissionConsignmentWarehouse` object — Commission/consignment warehouse for the sales order. This is used by the commission/consignment module.
      - `id` string
    - `storageCountry` string — Storage country of the sales order. This is used for tax calculations and compliance. Please note that the value of this field cannot be edited or viewed in the Xentral UI
    - `useAlternativeDocumentTitle` boolean — Indicates if the alternative document title should be used. The alternative document title can be configured per document type in the system settings.
    - `autoDispatch` boolean — Indicates if the sales order is available for auto dispatch.
    - `vatChecked` boolean — Indicates if the sales order has been checked for export / VAT compliance. For non-domestic sales orders, if this is false, the sales order cannot be dispatched.
    - `createDocuments` 'deliveryNote' | 'invoice' | 'deliveryNoteAndInvoice' — Indicates the type of documents that will be created if this sales order is processed using auto dispatch.
    - `manualPaymentApproval` boolean — Use this field to manual approve the payment of the sales order. Depending on the payment method configuration, this might be required before the sales order can be dispatched.
    - `manualShippingCostApproval` boolean — Use this field to manually approve the shipping costs of the sales order. Depending on the shipping method configuration, this might be required before the sales order can be dispatched.
    - `manualDeliveryBlockApproval` boolean — Use this field to manually approve the delivery block of the sales order. If this is true, the sales order can be dispatched despite having a delivery block.
    - `fastLane` boolean — Indicates if the sales order is a fast lane order. Fast lane orders are processed with higher priority during auto dispatch, and stock is allocated preferentially to them.
    - `disableCancellationEmail` boolean — Indicates if the cancellation email should be disabled for this sales order. If true, no cancellation email will be sent when the sales order is cancelled. Please note that the cancellation email has to be enabled in the project settings for this to take effect.
    - `disableTrackingEmail` boolean — Indicates if the tracking email should be disabled for this sales order. If true, no tracking email will be sent when the sales order is dispatched. Please note that the tracking email has to be enabled in the project and shipping method settings for this to take effect.
    - `disablePaymentEmail` boolean — Indicates if the payment email should be disabled for this sales order. If true, no payment email will be sent when the sales order is paid. Please note that the payment email has to be enabled in the project and payment method settings for this to take effect.
    - `deviatingDebtorAccountNumber` string — Deviating debtor account number for the sales order. Used for accounting export.
    - `lineItems` union[]
      - union
        - object — Sales Order Line Item
          - `type` 'product'
          - `id` string — ID of the line item.
          - `number` string — The Number of the line item. Usually the product SKU, but can be adjusted if required.
          - `name` string — The name of the line item. Usually the product name, but can be adjusted if required.
          - `description` string — The description of the line item. Usually the product description, but can be adjusted if required.
          - `quantity` number, float — The quantity of the line item.
          - `product` union — The product of the line item.
            - object
              - …
            - object
              - …
          - `countryOfOrigin` unknown
          - `hsCode` unknown
          - `customFields` object[] — Custom fields with their values and metadata.
            - `key` string
            - `value` string
            - `label` string
          - `unit` string — The unit of the line item.
          - `deliveryDate` string, date — The delivery date of the line item.
          - `deliveryDateAsCalendarWeek` boolean — Whether to show the delivery date as calendar week or explicit.
          - `packagingUnit` string — The unit of packaging for the line item.
          - `internalComment` string — Internal comment, does not show up on the document. Intended to be used for company-internal notes.
          - `customerProductNumber` string — Customer product number for the line item.
          - `order` integer — The ordering sequence of the line item.
          - `updatedAt` string, date-time — The date and time when the line item was last updated.
          - `createdAt` string, date-time — The date and time when the line item was created.
          - `taxRate` union — Tax rate type applied to this line item
            - 'standard' | 'reduced' | 'exempt'
            - number, float
          - `effectiveTaxRate` number, float — Effective tax rate for this line item
          - `price` object — Price information for this line item
            - `net` object — Money
              - …
            - `gross` object — Money
              - …
          - `discount` number, float — Discount percentage applied to this line item
          - `itemRevenue` object — Total revenue for all quantities of this line item
            - `net` object — Money
              - …
            - `gross` object — Money
              - …
          - `lineItemRevenue` object — Revenue for a single unit of this line item
            - `net` object — Money
              - …
            - `gross` object — Money
              - …
          - `purchasePrice` object — Purchase price information for this line item
            - `net` object — Money
              - …
          - `contributionMargin` number, float — Contribution margin for this line item
          - `taxLegalNotice` string — Legal notice regarding tax for this line item
          - `printSettings` object — Print settings for this line item.
            - `withoutPrice` boolean — Hide the prices for this line item when printing.
            - `hidden` boolean — Hide this line item when printing.
          - `externalNumber` string — External number for the line item, typically used for shop/web order line item references.
          - `hasChildLineItems` boolean — Indicates if this line item has child line items (exploded line items).
          - `parentLineItem` object — If this line item is a child line item, this will contain the parent line item ID.
            - `id` string
          - `desiredQualityControlAttributes` object — Desired quality control attributes for the line item.
            - `bestBeforeDate` string, date — Preferred best before date for the line item.
            - `batch` string — Preferred batch for the line item.
        - object
          - `id` string, required
          - `order` integer — The ordering sequence of the line item
          - `type` 'heading', required
          - `name` string
          - `description` string
        - object
          - `id` string, required
          - `order` integer — The ordering sequence of the line item
          - `type` 'subtotal', required
          - `name` string
          - `description` string
        - object
          - `id` string, required
          - `order` integer — The ordering sequence of the line item
          - `type` 'group_total', required
          - `name` string
          - `description` string
        - object
          - `id` string, required
          - `order` integer — The ordering sequence of the line item
          - `type` 'image', required
          - `name` string
          - `description` string
          - `image` object
            - `id` string
          - `imageHeight` unknown
          - `imageWidth` unknown
        - object
          - `id` string, required
          - `order` integer — The ordering sequence of the line item
          - `type` 'page_break', required
    - `directDebitDate` string, date — Direct debit date of the sales order. If the sales order is paid via direct debit, the direct debit will not be executed before this date
    - `shippingMethod` object — Shipping method of the sales order.
      - `id` string
    - `effectiveAddresses` object — Effective addresses of the sales order. These (read-only) postal addresses will always be set, regardless of whether a deviating ship-to address is set or not. Use these fields if you need to easily determine the ship-to and bill-to addresses of the sales order. For updating, use the `documentAddress` and `deviatingShipToAddress` fields.
      - `soldTo` object — Represents a postal address with contact information.
        - `name` string, required — Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc.
        - `type` 'mrs' | 'mr' | 'company' | 'other'
        - `title` string
        - `contactPerson` string
        - `department` string
        - `subDepartment` string
        - `addressSupplement` string
        - `street` string
        - `zipCode` string
        - `city` string
        - `state` string
        - `country` string
        - `salutation` string
        - `gln` string
        - `email` string
        - `phone` string
        - `fax` string
        - `mobile` string
      - `shipTo` object — Represents a postal address with contact information.
        - `name` string, required — Represents an address consisting of a physical address and contact information. It is used in various documents, such as invoices, delivery notes, etc.
        - `type` 'mrs' | 'mr' | 'company' | 'other'
        - `title` string
        - `contactPerson` string
        - `department` string
        - `subDepartment` string
        - `addressSupplement` string
        - `street` string
        - `zipCode` string
        - `city` string
        - `state` string
        - `country` string
        - `salutation` string
        - `gln` string
        - `email` string
        - `phone` string
        - `fax` string
        - `mobile` string
    - `masterReferenceNumber` string — Master reference number of the document
    - `salesChannel` object — Sales channel of the sales order. This is typically used to indicate the webshop or sales platform from which the order originated.
      - `id` string
    - `costCenter` string — Cost center of the document.

## Other responses

- `400` — Failed validation
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Problem occurred
- `429` — Too Many Requests

---

[API](https://skmtc.net/xentral/apis/xentral-api.md) · [All operations](https://skmtc.net/xentral/apis/xentral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xentral/xentral-api/revisions/8a27ba392442/schema)