--- updatedAt: 2026-04-23T13:29:19.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # Update sales order CAUTION: Positions not specified in the payload will be DELETED. Please pass the ids along if you need them to be preserved.

The sales order edit endpoint allows for updating an existing sales order. When updating, any positions not included in the positions payload will be implicitly deleted from the order. This ensures that the positions list in the payload accurately reflects the desired state of the sales order after the update. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Xentral API", "version": "v0.1", "description": "Xentral is an ERP platform.", "contact": { "name": "Xentral", "url": "https://xentral.com", "email": "api@xentral.com" } }, "tags": [ { "name": "Sales Order", "description": "SalesOrders are an outbound orders, meaning that someone has bought from you." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token obtained in POST /tokens endpoint or pregenerated in the system." } } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://{xentralId}.xentral.biz", "description": "Your Xentral Instance", "variables": { "xentralId": { "default": "xentral" } } }, { "url": "https://{domain}", "description": "Xentral at a custom domain", "variables": { "domain": { "default": "xentral.com" } } } ], "x-readme": { "samples-languages": [] }, "paths": { "/api/v1/salesOrders/{id}": { "patch": { "tags": [ "Sales Order" ], "operationId": "salesOrder.update", "summary": "Update sales order", "description": "CAUTION: Positions not specified in the payload will be DELETED. Please pass the ids along if you need them to be preserved.

The sales order edit endpoint allows for updating an existing sales order. When updating, any positions not included in the positions payload will be implicitly deleted from the order. This ensures that the positions list in the payload accurately reflects the desired state of the sales order after the update.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The resource's identifier.", "schema": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } ], "requestBody": { "description": "Sales order edit request payload", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "earliestFulfillmentDate": { "type": "string", "format": "date", "nullable": true }, "desiredDeliveryDate": { "type": "string", "format": "date", "description": "The desired delivery date for the sales order. Format: Y-m-d", "example": "2022-12-05", "nullable": true }, "reservationDate": { "type": "string", "format": "date", "description": "The reservation date for the sales order. Format: Y-m-d", "example": "2022-12-05", "nullable": true }, "desiredDeliveryDateAsCalendarWeek": { "type": "boolean", "description": "Flag indicating whether a calendar week should be printed on documents" }, "editor": { "type": "string", "description": "Creator of the Sales Order" }, "salesRepresentative": { "description": "Reference to the sales representative resource.", "type": "object", "required": [ "id" ], "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "The string Id" } }, "example": { "id": "123" } }, "externalOrderNumber": { "type": "string", "description": "Customer-facing sales order number in the originating shop system / platform (e.g. Shopify, Amazon, etc)" }, "externalOrderId": { "type": "string", "description": "technical sales order ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync status updates & tracking info back to the originating shop / platform" }, "transactionNumber": { "type": "string", "description": "transaction number typically used to identify payment transactions in the originating shop system / platforms (e.g. Shopify, Amazon, etc). This ID is typically used for financial reconciliation of payment transactions with sales orders / invoices in Xentral." }, "customerOrderNumber": { "type": "string", "description": "Purchase Order number from the customer’s purchase order system, typically used in B2B context." }, "autoCreateDocuments": { "type": "string", "enum": [ "deliveryNote+invoice", "deliveryNote", "invoice" ], "description": "Sets documents created by autoshippment." }, "bodyIntroduction": { "type": "string", "description": "Text displayed on the PDF print-out above the positions table. Rich-Text capable." }, "bodyOutroduction": { "type": "string", "description": "Text displayed on the PDF print-out below the positions table. Rich-Text capable." }, "internalDesignation": { "type": "string", "description": "Internal designation which is also displayed as grey text in the sales order list in the application. Unformatted string only." }, "comment": { "type": "string", "description": "Internal comment. Rich-Text capable." }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } } }, "customer": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "project": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "salesChannel": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "language": { "type": "object", "additionalProperties": false, "required": [ "iso2" ], "properties": { "iso2": { "type": "string", "description": "ISO 639-1 Code", "nullable": true } }, "description": "Language information for a Sales Order", "example": { "iso2": "DE" } }, "financials": { "type": "object", "additionalProperties": false, "properties": { "paymentMethod": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "currency": { "type": "string" }, "costCenter": { "type": "object", "additionalProperties": false, "nullable": true, "required": [ "id", "number" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "number": { "type": "string", "nullable": true } }, "example": { "id": "1", "number": "1234" } }, "billingAddress": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "mr", "mrs", "company", "other" ] }, "name": { "type": "string" }, "contactPerson": { "type": "string" }, "department": { "type": "string" }, "subDepartment": { "type": "string" }, "street": { "type": "string" }, "zipCode": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "addressSupplement": { "type": "string" }, "gln": { "type": "string" }, "salutation": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "tax": { "type": "object", "additionalProperties": false, "properties": { "taxation": { "type": "string", "enum": [ "domestic", "eu", "export", "taxfreedomestic" ] }, "vatId": { "type": "string" }, "taxDisplay": { "type": "string", "enum": [ "gross", "net", "auto" ] }, "noTaxInfoText": { "type": "boolean" }, "normalTaxRate": { "type": "number", "format": "float" }, "reducedTaxRate": { "type": "number", "format": "float" } } }, "paymentTerms": { "type": "object", "additionalProperties": false, "properties": { "paymentTargetDiscount": { "type": "number", "format": "float" }, "paymentTargetDays": { "type": "integer", "format": "int64" }, "paymentTargetDiscountDays": { "type": "integer", "format": "int64" }, "directDebitDate": { "type": "string", "format": "date", "nullable": true } } } }, "description": "Financial information for a Sales Order to update", "example": { "paymentMethod": { "id": "3" }, "currency": "EUR" } }, "delivery": { "type": "object", "additionalProperties": false, "properties": { "autoShipping": { "type": "boolean" }, "fastLane": { "type": "boolean" }, "shippingCosts": { "type": "array", "items": { "type": "object", "description": "CAUTION: shipping cost positions not included in the payload will be DELETED.
If you want to retain specific shipping cost positions, please provide their ids.

Any parameters or retained shipping cost position objects that are not provided in the payload remain unchanged.

If you don't include the shippingCosts parameter at all, all existing shipping cost positions will remain unchanged.", "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "shippingCostProduct", "quantity" ], "properties": { "quantity": { "type": "number", "format": "double" }, "comment": { "type": "string" }, "shippingCostProduct": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "name": { "type": "string" }, "description": { "type": "string" }, "freeFields": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "value" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "value": { "type": "string" } } } }, "number": { "type": "string", "nullable": true } } }, "tax": { "type": "object", "required": [ "taxText" ], "properties": { "vatCategory": { "type": "string", "nullable": true, "enum": [ "reduced", "normal", "exempt" ], "description": "VAT category. When importing a position only one of `rate` or `vatCategory` must be used.", "example": "reduced" }, "rate": { "type": "number", "format": "float", "example": 0.5, "nullable": true, "description": "VAT rate. When importing a position only one of `rate` or `vatCategory` must be used." }, "taxText": { "type": "string", "example": "Tax Text", "nullable": true, "description": "Tax Text" } } }, "price": { "description": "Money object with amount and currency", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float", "example": "24.99" }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "enum": [ "EUR", "USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF", "PLN", "RON", "SEK", "CHF", "ISK", "NOK", "HRK", "RUB", "TRY", "AUD", "BRL", "CAD", "CNY", "HKD", "IDR", "ILS", "INR", "KRW", "MXN", "MYR", "NZD", "PHP", "SGD", "THB", "ZAR", "ARS", "CLP", "SAR", "AED", "QAR" ], "description": "Currency matches one of currency values as specified in ISO-4217.", "example": "PLN" } } }, "discount": { "type": "number", "format": "float", "description": "percentage discount to be applied to the position, expressed as a decimal value (0.15 = 15% discount)" }, "webId": { "type": "string", "description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform" } } }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "quantity": { "type": "number", "format": "double" }, "comment": { "type": "string" }, "shippingCostProduct": { "type": "object", "additionalProperties": false, "description": "Whenever a Sales Order Position is being updated, the product used in it cannot be updated. If a different product wants to be used, the position will need to be removed and a new one using the new product will need to be created.", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "freeFields": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "value" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "value": { "type": "string" } } } }, "number": { "type": "string", "nullable": true } } }, "tax": { "type": "object", "required": [ "taxText" ], "properties": { "vatCategory": { "type": "string", "nullable": true, "enum": [ "reduced", "normal", "exempt" ], "description": "VAT category. When importing a position only one of `rate` or `vatCategory` must be used.", "example": "reduced" }, "rate": { "type": "number", "format": "float", "example": 0.5, "nullable": true, "description": "VAT rate. When importing a position only one of `rate` or `vatCategory` must be used." }, "taxText": { "type": "string", "example": "Tax Text", "nullable": true, "description": "Tax Text" } } }, "price": { "description": "Money object with amount and currency", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float", "example": "24.99" }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "enum": [ "EUR", "USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF", "PLN", "RON", "SEK", "CHF", "ISK", "NOK", "HRK", "RUB", "TRY", "AUD", "BRL", "CAD", "CNY", "HKD", "IDR", "ILS", "INR", "KRW", "MXN", "MYR", "NZD", "PHP", "SGD", "THB", "ZAR", "ARS", "CLP", "SAR", "AED", "QAR" ], "description": "Currency matches one of currency values as specified in ISO-4217.", "example": "PLN" } } }, "discount": { "type": "number", "format": "float", "description": "percentage discount to be applied to the position, expressed as a decimal value (0.15 = 15% discount)" }, "webId": { "type": "string", "description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform" } } } ] } }, "storageCountry": { "type": "string", "nullable": true, "description": "Use storageCountry for external fulfillment without delivery notes to set the country of fulfillment. If using delivery notes, do not use storageCountry." }, "preferredWarehouse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "nullable": false } }, "description": "Use preferredWarehouse for fulfillment with delivery notes to define which warehouse should be used." }, "shippingAddress": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "mr", "mrs", "company", "other" ] }, "name": { "type": "string" }, "department": { "type": "string" }, "contactPerson": { "type": "string" }, "subDepartment": { "type": "string" }, "street": { "type": "string" }, "zipCode": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "addressSupplement": { "type": "string" }, "gln": { "type": "string" }, "title": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "shippingMethod": { "description": "Reference to another resource", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "deliveryTerms": { "description": "Nullable reference to another resource", "type": "object", "additionalProperties": false, "nullable": true, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } } } }, "positions": { "type": "array", "description": "CAUTION: Positions not included in the payload will be DELETED.
If you want to retain specific positions, please provide their ids.

Any parameters of retained position objects that are not provided in the payload remain unchanged.

If you don't include the positions parameter at all, all existing positions will remain unchanged.", "items": { "type": "object", "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "product", "quantity" ], "properties": { "quantity": { "type": "number", "format": "double" }, "comment": { "type": "string" }, "product": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "name": { "type": "string" }, "description": { "type": "string" }, "freeFields": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "value" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "value": { "type": "string" } } } }, "number": { "type": "string", "nullable": true } } }, "tax": { "type": "object", "required": [ "taxText" ], "properties": { "vatCategory": { "type": "string", "nullable": true, "enum": [ "reduced", "normal", "exempt" ], "description": "VAT category. When editing/creating a position only one of `rate` or `vatCategory` must be used.", "example": "reduced" }, "rate": { "type": "number", "format": "float", "example": 0.5, "nullable": true, "description": "VAT rate. When editing/creating a position only one of `rate` or `vatCategory` must be used." }, "taxText": { "type": "string", "example": "Tax Text", "nullable": true, "description": "Tax Text" } } }, "price": { "description": "Money object with amount and currency", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float", "example": "24.99" }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "enum": [ "EUR", "USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF", "PLN", "RON", "SEK", "CHF", "ISK", "NOK", "HRK", "RUB", "TRY", "AUD", "BRL", "CAD", "CNY", "HKD", "IDR", "ILS", "INR", "KRW", "MXN", "MYR", "NZD", "PHP", "SGD", "THB", "ZAR", "ARS", "CLP", "SAR", "AED", "QAR" ], "description": "Currency matches one of currency values as specified in ISO-4217.", "example": "PLN" } } }, "discount": { "type": "number", "format": "float", "description": "percentage discount to be applied to the position, expressed as a decimal value (0.15 = 15% discount)" }, "webId": { "type": "string", "description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform" }, "desiredDeliveryDate": { "type": "string", "format": "date", "description": "Date of creation desired delivery date", "nullable": true, "example": "2025-01-01" }, "desiredDeliveryDateAsCalendarWeek": { "type": "boolean", "description": "Indicating whether a calendar week should be printed on documents or the actual date) is readable and editable via API", "example": false }, "desiredQualityControlAttributes": { "type": "object", "nullable": true, "properties": { "batch": { "type": "string", "nullable": true }, "bestBeforeDate": { "type": "string", "format": "date", "nullable": true } } } } }, { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "quantity": { "type": "number", "format": "double" }, "comment": { "type": "string" }, "product": { "type": "object", "additionalProperties": false, "description": "Whenever a Sales Order Position is being updated, the product used in it cannot be updated. If a different product wants to be used, the position will need to be removed and a new one using the new product will need to be created.", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "freeFields": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "value" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "value": { "type": "string" } } } }, "number": { "type": "string", "nullable": true } } }, "tax": { "type": "object", "properties": { "vatCategory": { "type": "string", "nullable": true, "enum": [ "reduced", "normal", "exempt" ], "description": "VAT category. When editing/creating a position only one of `rate` or `vatCategory` must be used.", "example": "reduced" }, "rate": { "type": "number", "format": "float", "example": 0.5, "nullable": true, "description": "VAT rate. When editing/creating a position only one of `rate` or `vatCategory` must be used." }, "taxText": { "type": "string", "example": "Tax Text", "nullable": true, "description": "Tax Text" } } }, "price": { "description": "Money object with amount and currency", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float", "example": "24.99" }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "enum": [ "EUR", "USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF", "PLN", "RON", "SEK", "CHF", "ISK", "NOK", "HRK", "RUB", "TRY", "AUD", "BRL", "CAD", "CNY", "HKD", "IDR", "ILS", "INR", "KRW", "MXN", "MYR", "NZD", "PHP", "SGD", "THB", "ZAR", "ARS", "CLP", "SAR", "AED", "QAR" ], "description": "Currency matches one of currency values as specified in ISO-4217.", "example": "PLN" } } }, "discount": { "type": "number", "format": "float", "description": "percentage discount to be applied to the position, expressed as a decimal value (0.15 = 15% discount)" }, "webId": { "type": "string", "description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform" }, "desiredDeliveryDate": { "type": "string", "format": "date", "description": "Date of creation desired delivery date", "nullable": true, "example": "2025-01-01" }, "desiredDeliveryDateAsCalendarWeek": { "type": "boolean", "description": "Indicating whether a calendar week should be printed on documents or the actual date) is readable and editable via API", "example": false }, "desiredQualityControlAttributes": { "type": "object", "nullable": true, "properties": { "batch": { "type": "string", "nullable": true }, "bestBeforeDate": { "type": "string", "format": "date", "nullable": true } } } } } ] } }, "discountPositions": { "type": "array", "description": "CAUTION: Discount positions not included in the payload will be DELETED.
If you want to retain specific discount positions, please provide their ids.

Any parameters or retained discount position objects that are not provided in the payload remain unchanged.

If you don't include the discountPositions parameter at all, all existing discount positions will remain unchanged.", "items": { "type": "object", "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "discountProduct", "quantity" ], "properties": { "quantity": { "type": "number", "format": "double" }, "discountProduct": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "name": { "type": "string" }, "description": { "type": "string" }, "freeFields": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "value" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "value": { "type": "string" } } } }, "number": { "type": "string", "nullable": true } } }, "tax": { "type": "object", "required": [ "taxText" ], "properties": { "vatCategory": { "type": "string", "nullable": true, "enum": [ "reduced", "normal", "exempt" ], "description": "VAT category. When editing/creating a position only one of `rate` or `vatCategory` must be used.", "example": "reduced" }, "rate": { "type": "number", "format": "float", "example": 0.5, "nullable": true, "description": "VAT rate. When editing/creating a position only one of `rate` or `vatCategory` must be used." }, "taxText": { "type": "string", "example": "Tax Text", "nullable": true, "description": "Tax Text" } } }, "value": { "description": "Money object with amount and currency", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float", "example": "24.99" }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "enum": [ "EUR", "USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF", "PLN", "RON", "SEK", "CHF", "ISK", "NOK", "HRK", "RUB", "TRY", "AUD", "BRL", "CAD", "CNY", "HKD", "IDR", "ILS", "INR", "KRW", "MXN", "MYR", "NZD", "PHP", "SGD", "THB", "ZAR", "ARS", "CLP", "SAR", "AED", "QAR" ], "description": "Currency matches one of currency values as specified in ISO-4217.", "example": "PLN" } } }, "webId": { "type": "string", "description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform" } } }, { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "quantity": { "type": "number", "format": "double" }, "discountProduct": { "type": "object", "additionalProperties": false, "description": "Whenever a Sales Order Position is being updated, the product used in it cannot be updated. If a different product wants to be used, the position will need to be removed and a new one using the new product will need to be created.", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "freeFields": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "required": [ "id", "value" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "value": { "type": "string" } } } }, "number": { "type": "string", "nullable": true } } }, "tax": { "type": "object", "properties": { "vatCategory": { "type": "string", "nullable": true, "enum": [ "reduced", "normal", "exempt" ], "description": "VAT category. When editing/creating a position only one of `rate` or `vatCategory` must be used.", "example": "reduced" }, "rate": { "type": "number", "format": "float", "example": 0.5, "nullable": true, "description": "VAT rate. When editing/creating a position only one of `rate` or `vatCategory` must be used." }, "taxText": { "type": "string", "example": "Tax Text", "nullable": true, "description": "Tax Text" } } }, "value": { "description": "Money object with amount and currency", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float", "example": "24.99" }, "currency": { "type": "string", "pattern": "[A-Z]{3}", "enum": [ "EUR", "USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF", "PLN", "RON", "SEK", "CHF", "ISK", "NOK", "HRK", "RUB", "TRY", "AUD", "BRL", "CAD", "CNY", "HKD", "IDR", "ILS", "INR", "KRW", "MXN", "MYR", "NZD", "PHP", "SGD", "THB", "ZAR", "ARS", "CLP", "SAR", "AED", "QAR" ], "description": "Currency matches one of currency values as specified in ISO-4217.", "example": "PLN" } } }, "webId": { "type": "string", "description": "technical position ID in the originating shop system / platform (e.g. Shopify, Amazon, etc). This ID is used to sync info back to the originating shop / platform" } } } ] } }, "vatCheck": { "type": "boolean", "description": "Text displayed on the PDF." } } }, "examples": { "Update sales order": { "value": { "date": "2023-12-01", "earliestFulfillmentDate": "2022-12-05", "desiredDeliveryDate": "2022-12-05", "reservationDate": "2022-12-05", "desiredDeliveryDateAsCalendarWeek": false, "editor": "Administrator", "salesRepresentative": { "id": "1" }, "externalOrderNumber": "120013", "externalOrderId": "453894034", "customer": { "id": "394" }, "project": { "id": "4" }, "salesChannel": { "id": "3" }, "language": { "iso2": "de" }, "financials": { "paymentMethod": { "id": "1" }, "currency": "EUR", "billingAddress": { "type": "mrs", "name": "Jane Doe", "street": "Musterstraße 1", "zipCode": "12345", "city": "Musterstadt", "country": "DE" }, "tax": { "taxation": "domestic", "taxDisplay": "gross" } }, "delivery": { "autoShipping": true, "fastLane": false, "shippingAddress": { "type": "mrs", "name": "Jane Doe", "street": "Musterstraße 1", "zipCode": "12345", "city": "Musterstadt", "country": "DE" }, "shippingMethod": { "id": "4" }, "storageCountry": "DE", "shippingCosts": [ { "shippingCostProduct": { "id": "453" }, "quantity": 1 } ] }, "positions": [ { "product": { "id": "241" }, "quantity": 1, "price": { "amount": "10.00", "currency": "EUR" }, "tax": { "taxText": "19% MwSt.", "vatCategory": "normal" }, "webId": "2395028", "desiredDeliveryDate": "2023-11-11", "desiredDeliveryDateAsCalendarWeek": false }, { "product": { "id": "494" }, "quantity": 4, "price": { "amount": "20.00", "currency": "EUR" }, "discount": 10, "tax": { "taxText": "7% MwSt.", "vatCategory": "reduced" }, "webId": "2395029", "desiredDeliveryDate": "2023-11-11", "desiredDeliveryDateAsCalendarWeek": false } ], "vatCheck": false } }, "Update sales order with different positions": { "value": { "date": "2023-12-01", "earliestFulfillmentDate": "2022-12-05", "externalOrderNumber": "120013", "customer": { "id": "394" }, "project": { "id": "4" }, "salesChannel": { "id": "3" }, "language": { "iso2": "de" }, "financials": { "paymentMethod": { "id": "1" }, "currency": "EUR", "billingAddress": { "type": "mrs", "name": "Jane Doe", "street": "Musterstraße 1", "zipCode": "12345", "city": "Musterstadt", "country": "DE" }, "tax": { "taxation": "domestic", "taxDisplay": "gross" } }, "delivery": { "autoShipping": true, "fastLane": false, "shippingAddress": { "type": "mrs", "name": "Jane Doe", "street": "Musterstraße 1", "zipCode": "12345", "city": "Musterstadt", "country": "DE" }, "shippingMethod": { "id": "4" }, "preferredWarehouse": { "id": "1" }, "shippingCosts": [ { "id": "2", "shippingCostProduct": { "name": "update shipping Cost Product" }, "quantity": 1 } ] }, "positions": [ { "id": "1", "quantity": 1, "price": { "amount": "10.00", "currency": "EUR" }, "tax": { "taxText": "19% MwSt.", "vatCategory": "normal" }, "webId": "2395028", "desiredDeliveryDate": "2023-11-11", "desiredDeliveryDateAsCalendarWeek": false }, { "product": { "id": "494" }, "quantity": 4, "price": { "amount": "20.00", "currency": "EUR" }, "discount": 10, "tax": { "taxText": "7% MwSt.", "vatCategory": "reduced" }, "webId": "2395029", "desiredDeliveryDate": "2023-11-11", "desiredDeliveryDateAsCalendarWeek": false } ], "discountPositions": [ { "id": "3", "quantity": 1 } ] } } } } } }, "responses": { "204": { "description": "Operation completed successfully, no response body" }, "400": { "description": "IETF RFC 9457 Problem API compliant response", "content": { "application/problem+json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "title", "violations" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/request-validation" ] }, "title": { "type": "string", "minLength": 1, "example": "Request payload validation failed." }, "violations": { "oneOf": [ { "type": "array", "items": { "type": "object", "example": { "username": [ "This value should not be blank." ], "email": [ "This value is not a valid email address." ] } }, "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages." }, { "type": "object", "example": { "_": [ "This value should contain at most `9` elements." ] }, "description": "This field will be a mirrored request payload with only invalid fields and values replaced by error messages." } ] } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/generic-validation" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/conflict" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "items" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/conflictItems" ] }, "title": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "title", "messages" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "array", "items": { "type": "string" } } } } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "scopes" ], "properties": { "type": { "type": "string", "enum": [ "https://developer.xentral.com/reference/problems#token-scopes" ] }, "title": { "type": "string", "minLength": 1 }, "scopes": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "title", "messages" ], "properties": { "type": { "type": "string", "enum": [ "https://api.xentral.biz/problems/generic-validation" ] }, "title": { "type": "string", "minLength": 1 }, "messages": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } ] } } } }, "403": { "description": "Unable to authorize the client" }, "404": { "description": "Resource was not found or not enough access privileges" }, "406": { "description": "Requested resource representation does not exist." } } } } } } ```