--- updatedAt: 2026-05-27T08:29:53.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # Update product v1 Updates details of a single product # 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": "Product", "description": "Product represents the services or things given company sells in the business." } ], "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/products/{id}": { "patch": { "tags": [ "Product" ], "operationId": "product.update", "deprecated": true, "summary": "Update product v1", "description": "Updates details of a single product", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The resource's identifier.", "schema": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } ], "requestBody": { "description": "Product update request payload", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Name of the product." }, "number": { "type": "string", "description": "Number / SKU of the product." }, "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" } }, "description": { "type": "string", "nullable": true, "description": "Description of the product." }, "internalComment": { "type": "string", "nullable": true, "description": "Text only for internal information." }, "shortDescription": { "type": "string", "nullable": true, "description": "Short description of the product." }, "customsTariffNumber": { "type": "string", "nullable": true, "description": "Customs tariff number of the product." }, "ean": { "type": "string", "nullable": true, "description": "EAN of the product." }, "minimumOrderQuantity": { "type": "number", "description": "Numerical minimum order quantity of the product." }, "minimumStorageQuantity": { "type": "number", "description": "Numerical minimum storage quantity of the product." }, "allowPurchaseFromAllSuppliers": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "hasBatches": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "serialNumbersMode": { "type": "string", "enum": [ "disabled", "user", "product", "productAndWarehouse" ], "description": "4 different modes available if the product has serial numbers or not and how they are handled. For more information about the different modes have a look into our handbook." }, "hasBestBeforeDate": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "hasBillOfMaterials": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "isAssembledJustInTime": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "isProductionProduct": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "isExternallyProduced": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "isDisabled": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "disabledReason": { "type": "string", "nullable": true, "description": "Shows the reason why the product is locked when clicking into the product." }, "hidePriceOnDocuments": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "ageRating": { "type": "string", "enum": [ "", "16", "18" ], "nullable": true, "description": "Sets an age rating for the product. Currently only used for the shipping service provider DHL." }, "countryOfOrigin": { "type": "string", "pattern": "[A-Z]{2}", "nullable": true, "description": "Two-digit ISO country code for country of origin of the product." }, "regionOfOrigin": { "type": "string", "enum": [ "", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13", "14", "15", "16", "99" ], "description": "01 - Schleswig-Holstein, 02 - Hamburg, 03 - Niedersachsen, 04 - Bremen, 05 - Nordhrein-Westfalen, 06 - Hessen, 07 - Rheinland-Pfalz, 08 - Baden-Württemberg, 09 - Bayern, 10 - Saarland, 11 - Berlin, 12 - Brandenburg, 13 - Mecklenburg-Vorpommern, 14 - Sachsen, 15 - Sachsen-Anhalt, 16 - Thüringen, 99 - foreign origin", "nullable": true }, "measurements": { "type": "object", "additionalProperties": false, "properties": { "width": { "x-description-missing": true, "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "properties": { "value": { "type": "number", "format": "float" }, "unit": { "type": "string", "enum": [ "cm" ], "description": "Currently only cm as unit allowed." } }, "example": { "value": 20, "unit": "cm" } }, "height": { "x-description-missing": true, "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "properties": { "value": { "type": "number", "format": "float" }, "unit": { "type": "string", "enum": [ "cm" ], "description": "Currently only cm as unit allowed." } }, "example": { "value": 20, "unit": "cm" } }, "length": { "x-description-missing": true, "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "properties": { "value": { "type": "number", "format": "float" }, "unit": { "type": "string", "enum": [ "cm" ], "description": "Currently only cm as unit allowed." } }, "example": { "value": 20, "unit": "cm" } }, "weight": { "x-description-missing": true, "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "properties": { "value": { "type": "number", "format": "float", "example": 10.5 }, "unit": { "type": "string", "enum": [ "kg" ], "description": "Currently only kg as unit allowed.", "example": "kg" } }, "example": { "value": 20, "unit": "kg" } }, "netWeight": { "x-description-missing": true, "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "properties": { "value": { "type": "number", "format": "float", "example": 10.5 }, "unit": { "type": "string", "enum": [ "kg" ], "description": "Currently only kg as unit allowed.", "example": "kg" } }, "example": { "value": 20, "unit": "kg" } } }, "example": { "width": { "value": 20, "unit": "cm" }, "height": { "value": 10, "unit": "cm" }, "length": { "value": 30, "unit": "cm" }, "weight": { "value": 2, "unit": "kg" }, "netWeight": { "value": 1.5, "unit": "kg" } } }, "manufacturer": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true, "description": "Name of the manufacturer." }, "number": { "type": "string", "nullable": true, "description": "Product number at the manufacturer." }, "link": { "type": "string", "nullable": true, "description": "URI of the manufacturer." } } }, "isStockItem": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "isStockTakingDisabled": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "hideJustInTimeItemsOnDocuments": { "description": "Loose boolean type which accepts boolean, number 0 or 1 and string 'true' or 'false'", "example": "'true'", "oneOf": [ { "type": "boolean" }, { "type": "number", "enum": [ 0, 1 ] }, { "type": "string", "enum": [ "true", "false", "True", "False", "TRUE", "FALSE" ] } ] }, "salesTax": { "type": "string", "enum": [ "standard", "reduced", "free" ], "description": "Selection of three possible values for the sales tax of the product." }, "shopPriceDisplay": { "type": "string", "format": "float", "nullable": true, "description": "Only used by some online shops. For more information have a look into our handbook." }, "isShippingCostsProduct": { "type": "boolean", "description": "Determines if a product is used as a shipping costs product. For more information have a look into our handbook." }, "discount": { "type": "object", "additionalProperties": false, "properties": { "isDiscountProduct": { "type": "boolean", "description": "Determines if a product is used as a discount. For more information have a look into our handbook." }, "discountPercentage": { "type": "number", "format": "float", "description": "Sets the discount value if the product is a discount. For more information have a look into our handbook." } } }, "stockTaking": { "type": "object", "additionalProperties": false, "description": "Contains settings for stock taking.", "properties": { "hasStockTakingValue": { "type": "boolean", "description": "Determines if the stock taking value should be used instead of the purchase price for stock taking." }, "stockTakingValue": { "type": "number", "format": "float", "description": "Sets the stock taking value for stock taking." } } }, "calculatedPurchasePrice": { "type": "object", "additionalProperties": false, "description": "Contains settings for the calculated purchase price.", "properties": { "hasCalculatedPurchasePrice": { "type": "boolean", "description": "Sets if the calculatedPurchasePrice should be used." }, "price": { "description": "Money object with amount and currency. If no currency is set, EUR is returned.", "example": { "amount": "13.37", "currency": "EUR" }, "type": "object", "additionalProperties": false, "properties": { "amount": { "description": "A string representing the amount", "type": "string", "format": "float" }, "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" } } } } }, "isMatrixProduct": { "type": "boolean", "description": "Determines if a product is a matrix product. For more information have a look into our handbook." }, "category": { "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" } }, "standardSupplier": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "nullable": true, "x-example-ignore": true, "description": "Nullable resource identifier" } }, "description": "Reference to a standard supplier for this product", "nullable": true, "example": { "id": "12345" } }, "defaultStorageLocation": { "nullable": true, "description": "Default storage location (storage bin) for the product. Maps to artikel.lager_platz.", "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1337" } }, "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": { "x-description-missing": true, "type": "string", "example": "Sample Product" } } } }, "options": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "name": { "type": "string" }, "values": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "name": { "type": "string" }, "sort": { "nullable": true, "type": "integer" } } } } } } }, "selectedOptions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." }, "option": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } } } } }, "tags": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "pattern": "\\d+", "description": "Either ID or name and key." }, "key": { "x-description-missing": true, "type": "string" }, "name": { "x-description-missing": true, "type": "string" }, "color": { "type": "string", "pattern": "[a-fA-F0-9]{6}", "example": "ff0000", "description": "Hexadecimal color value in 6-digit format without the leading # character." } } } }, "variantOf": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "description": "Reference to a parent product", "nullable": true, "example": { "id": "parent-product-98765" } } } }, "examples": { "Update Product": { "value": { "name": "Test Product Beverage", "description": "This is a very long description for the Test Product Beverage.", "shortDescription": "This is a short description.", "project": { "id": "7" }, "category": { "id": "1001" }, "customsTariffNumber": "12345678", "ean": "1234567890", "internalComment": "Attention: Only available for customers over the age of 18.", "minimumOrderQuantity": 100, "minimumStorageQuantity": 30, "allowPurchaseFromAllSuppliers": false, "hidePriceOnDocuments": false, "hasBatches": true, "serialNumbersMode": "disabled", "hasBestBeforeDate": true, "hasBillOfMaterials": false, "isAssembledJustInTime": false, "isProductionProduct": false, "isExternallyProduced": false, "isDisabled": false, "countryOfOrigin": "DE", "regionOfOrigin": "01", "salesTax": "standard", "isStockItem": true, "manufacturer": { "name": "Beverage Manufacturer", "number": "BM#1", "link": "https://example.com" }, "ageRating": "18", "defaultStorageLocation": { "id": "7" }, "freeFields": [ { "id": "8", "value": "FF8" } ], "variantOf": { "id": "1336" } } } } } } }, "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" } } } } } ] } } } }, "401": { "description": "Unable to authenticate the client", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message explaining why the request failed.", "example": "Missing required scopes: customer:create." } } }, "example": { "message": "Missing required scopes: customer:create." } }, "text/html": { "schema": { "type": "string", "example": "Unauthorized" } } } }, "403": { "description": "Unable to authorize the client" }, "404": { "description": "Resource was not found or not enough access privileges" }, "409": { "description": "Request conflict with the current state of the target resource", "content": { "application/problem+json": { "schema": { "oneOf": [ { "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" } } } } } } } ] } } } }, "415": { "description": "Resource representation send in the request is not supported." }, "429": { "description": "Too many API calls made." } } } } } } ```