--- updatedAt: 2026-04-23T13:29:19.000Z agentTools: projectIndex: https://developer.xentral.com/llms.txt --- # Update customer Update an existing customer. # 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": "Customer", "description": "Customer represents an information related to company, or individual person." } ], "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/v2/customers/{id}": { "patch": { "tags": [ "Customer" ], "operationId": "customer.update.v2", "summary": "Update customer", "description": "Update an existing customer.", "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The customer's identifier.", "schema": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } ], "requestBody": { "description": "Request structure to update a customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerType": { "type": "string", "nullable": true, "description": "Discriminator to create a company. If 'company' is used then 'name' is required. If 'person' is used then 'firstname' and 'lastname' are required.", "enum": [ "person", "company" ] }, "firstname": { "type": "string", "nullable": true, "description": "Firstname of customer", "example": "Max" }, "lastname": { "type": "string", "nullable": true, "description": "Lastname of customer", "example": "Mustmermann" }, "name": { "type": "string", "nullable": true, "description": "Name of the company", "example": "General Cosmic Company" }, "title": { "type": "string", "nullable": true, "description": "Title prefix for customer name. It will be used for communication.", "example": "Prof. Dr." }, "birthdate": { "type": "string", "format": "date", "nullable": true, "description": "Birhtdate of customer", "example": "2024-03-01" }, "number": { "type": "string", "nullable": true, "description": "Customer number. if this is not provided default number ranges will be applied automatically", "example": "C700001" }, "deviatingCustomerNumber": { "type": "string", "nullable": true, "description": "Deviating Customer number.", "example": "C711223" }, "salutation": { "type": "string", "enum": [ "mr", "mrs", "company", "other" ], "nullable": true, "description": "Decide kind of person if necessary. This value is e.g. responsible to apply automatic rules for salutation", "example": "mr" }, "salutationPhrase": { "type": "string", "nullable": true, "description": "You can specify a salutation how a customer/company should be addressed and override automatic rules.", "example": "Dear Sir" }, "department": { "type": "string", "nullable": true, "description": "Specify a department for customer", "example": "Sales" }, "subDepartment": { "type": "string", "nullable": true, "description": "Specify a sub-department for customer", "example": "Onlines Sales" }, "contactDetails": { "type": "object", "additionalProperties": false, "description": "Contact information of a customer", "properties": { "phone": { "type": "string", "nullable": true, "description": "Phone number of a customer", "example": "+49(30)12093756" }, "mobile": { "type": "string", "nullable": true, "description": "Mobile number of a customer", "example": "+49(172)56565656" }, "fax": { "type": "string", "nullable": true, "description": "Fax number of a customer", "example": "+49(30)12093756-1" }, "email": { "type": "string", "nullable": true, "description": "Email address of a customer", "example": "customer@domain.tpl" }, "website": { "type": "string", "nullable": true, "description": "URL of customers website" }, "additionalData": { "type": "array", "description": "List of additional not default contact data", "items": { "type": "object", "additionalProperties": false, "nullable": true, "required": [ "label", "value" ], "properties": { "label": { "type": "string", "description": "Specific key for customer contact data", "example": "mobile2" }, "value": { "type": "string", "nullable": true, "description": "Value for specified customers contact data key", "example": "+1(800)555 12235" } } } } } }, "accountManager": { "type": "object", "additionalProperties": false, "nullable": true, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } }, "salesManager": { "type": "object", "additionalProperties": false, "nullable": true, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } }, "isLead": { "type": "boolean", "nullable": false, "description": "Decides if customer is a lead", "example": true }, "contactPerson": { "type": "string", "nullable": true, "description": "Name of contact person", "example": "Milo Thatch" }, "groups": { "type": "array", "nullable": true, "description": "Specify the list of groups the customer should belong to", "items": { "type": "integer", "description": "ID of the group" } }, "customFields": { "type": "array", "description": "List of custom field values", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "value" ], "properties": { "id": { "type": "integer", "nullable": false, "description": "Identifier of custom field (max range: 1-20)", "example": 1 }, "value": { "type": "string", "nullable": true, "description": "Value of custom field", "example": "HS Deal - Open" } } } }, "financials": { "type": "object", "additionalProperties": false, "description": "Financial information of a customer", "properties": { "tax": { "type": "object", "additionalProperties": false, "description": "Tax information", "properties": { "taxation": { "type": "string", "enum": [ "domestic", "eu-delivery", "export", "free" ], "description": "Taxation settings", "example": "domestic" }, "taxDisplay": { "type": "string", "enum": [ "automatically", "always-net", "always-gross" ], "description": "Display of receipts with gross / net values.", "example": "always-net" }, "useDeliveryThreshold": { "type": "boolean", "description": "Use delivery threshold", "example": true }, "taxNumber": { "type": "string", "nullable": true, "description": "Tax number", "example": "l2/345/67890" }, "vatId": { "type": "string", "nullable": true, "description": "VAT ID of customer", "example": "DE124356789" } } }, "paymentTerms": { "type": "object", "additionalProperties": false, "description": "Payment terms", "properties": { "fixedPaymentTerms": { "type": "boolean", "description": "Fixed payment terms", "example": true }, "paymentTargetDays": { "type": "integer", "nullable": true, "description": "Payment terms target in days", "example": 14 }, "paymentTargetDiscount": { "type": "number", "nullable": false, "description": "Payment terms target discount", "example": 25.95 }, "paymentTargetDiscountDays": { "type": "integer", "nullable": true, "description": "Payment terms discount days", "example": 7 } } }, "paymentMethod": { "type": "object", "additionalProperties": false, "nullable": true, "required": [ "id" ], "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } } }, "subscriptionPaymentMethod": { "type": "string", "enum": [ "invoice", "direct-debit" ], "nullable": true, "description": "Payment method for subscriptions", "example": "invoice" }, "customsInformation": { "type": "string", "nullable": true, "description": "Customs information", "example": "" }, "creditLimit": { "type": "number", "format": "float", "description": "Credit limit", "example": 0 }, "defaultCurrency": { "type": "string", "nullable": false, "description": "Default currency for this customer", "example": "EUR" } }, "example": { "tax": { "taxation": "eu-delivery", "taxDisplay": "always-gross", "useDeliveryThreshold": false, "taxNumber": "1234", "vatId": "1234" }, "paymentTerms": { "fixedPaymentTerms": true, "paymentTargetDays": 99, "paymentTargetDiscount": 2.5, "paymentTargetDiscountDays": 5 }, "paymentMethod": { "id": "3" }, "subscriptionPaymentMethod": "invoice", "customsInformation": "Remarks regarding customs", "creditLimit": 0, "defaultCurrency": "EUR" } }, "primaryBankAccount": { "type": "object", "additionalProperties": false, "description": "", "properties": { "bankName": { "type": "string", "description": "Name of bank institute", "example": "Deutsche Bank" }, "owner": { "type": "string", "nullable": true, "description": "Name of account owner", "example": "Max Mustermann" }, "iban": { "type": "string", "nullable": true, "description": "International Bank Account Number", "example": "DE89370400440532013000" }, "bic": { "type": "string", "nullable": true, "description": "Bank Identifier Code", "example": "DEUTDEFFXXX" }, "sepa": { "type": "object", "additionalProperties": false, "description": "Object contains SEPA information", "properties": { "companySepa": { "type": "boolean", "description": "Different SEPA mandate especially foir companies", "example": true }, "mandateReference": { "type": "string", "nullable": true, "description": "Mandate reference", "example": "K21124DE60S21F2S09WX11G4FY" }, "mandateReferenceChange": { "type": "boolean", "description": "Set to true if mandate reference changes for this customer", "example": false }, "mandateReferenceDate": { "type": "string", "format": "date", "nullable": true, "description": "Mandate reference date", "example": "2025-03-01" }, "usage": { "type": "string", "enum": [ "recurring", "single" ], "description": "Type of usage: singe mandate or recurring one", "example": "recurring" }, "initial": { "type": "boolean", "description": "Set to true if it is first usage of this mandate", "example": true }, "remark": { "type": "string", "nullable": true, "description": "Additional comment", "example": "This is a comment" } } } }, "example": { "bankName": "XYZ Bank", "owner": "Name of the owner", "iban": "DE89370400440532013000", "bic": "DEUTDEFFXXX", "sepa": { "companySepa": true, "mandateReference": "K21124DE60S21F2S09WX11G4FY", "mandateReferenceChange": false, "mandateReferenceDate": "2025-03-01", "usage": "recurring", "initial": true, "remark": "This is a comment" } } }, "documentDelivery": { "type": "object", "additionalProperties": false, "description": "Additional settings for document delivery", "properties": { "autoCreateDocuments": { "type": "string", "enum": [ "both", "delivery_note", "invoice" ], "description": "Create receipts in auto-shipping", "example": "both" }, "invoiceAlwaysPaper": { "type": "boolean", "description": "Even with automatic dispatch, a paper invoice is always created", "example": true }, "amountInvoicePrints": { "type": "integer", "nullable": true, "description": "Number of printouts during shipping", "example": 2 }, "preferFax": { "type": "boolean", "description": "Prefer sending by FAX", "example": true } } }, "language": { "type": "string", "nullable": true, "description": "Language ISO code for customer communication", "example": "de" }, "mainProject": { "type": "object", "additionalProperties": false, "required": [ "id" ], "description": "Main Project id", "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "1" } }, "commission": { "type": "number", "format": "float", "nullable": false, "description": "Commission percentage for this customer", "example": 5.5 }, "identifier": { "type": "string", "nullable": true, "description": "Custom identifier for the customer", "example": "CUST-001" }, "logfile": { "type": "string", "nullable": false, "description": "Log entries of customer activities", "example": "customer.log" }, "lat": { "type": "number", "format": "float", "nullable": true, "description": "Latitude coordinate", "example": 52.520008 }, "lng": { "type": "number", "format": "float", "nullable": true, "description": "Longitude coordinate", "example": 13.404954 }, "fromShop": { "type": "object", "additionalProperties": false, "required": [ "id" ], "description": "Shop where customer originated from", "properties": { "id": { "type": "string", "pattern": "\\d+", "example": "17", "description": "Resource identifier." } }, "example": { "id": "5" } }, "marketing": { "type": "object", "additionalProperties": false, "description": "Marketing preferences and settings", "properties": { "marketingBan": { "type": "boolean", "description": "Whether marketing is banned for this customer", "example": false }, "showBirthdayInCalendar": { "type": "boolean", "description": "Show customer birthday in calendar", "example": true }, "birthdayCard": { "type": "boolean", "description": "Send birthday card to customer", "example": true }, "ageApproval": { "type": "boolean", "description": "Customer has approved age verification", "example": true } }, "example": { "marketingBan": false, "showBirthdayInCalendar": true, "birthdayCard": true, "ageApproval": true } }, "shipping": { "type": "object", "additionalProperties": false, "description": "Shipping information", "properties": { "freeShipping": { "type": "boolean", "description": "Indicates if free shipping is enabled for this customer", "example": true }, "trackingMailBan": { "type": "boolean", "description": "Indicates if tracking mail is banned for this customer", "example": false }, "deliveryBan": { "type": "boolean", "description": "Indicates if delivery is banned for this customer", "example": false }, "freeShippingFrom": { "type": "number", "format": "float", "description": "Minimum order amount for free shipping", "example": 50 }, "deliveryBanReason": { "type": "string", "description": "Reason for delivery ban", "nullable": true }, "deliveryBanDate": { "type": "string", "format": "date", "description": "Date when delivery ban was set", "nullable": true, "example": "2025-09-24" }, "shippingMethod": { "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" } } }, "example": { "freeShipping": true, "trackingMailBan": false, "deliveryBan": false, "freeShippingFrom": 50, "deliveryBanReason": "invalid address", "shippingMethod": { "id": "1" } } } } }, "examples": { "Update Customer": { "value": { "number": "70001", "deviatingCustomerNumber": "711223", "customerType": "person", "name": "General Cosmic Company", "firstname": "Max", "lastname": "Mustermann", "title": "Prof. Dr.", "salutation": "mr", "salutationPhrase": "Dear owners", "birthdate": "1970-01-01", "department": "Sales", "subDepartment": "Online Sales", "contactDetails": { "phone": "+49(30)111333555", "mobile": "+49(172)99988877", "fax": "+49(30)111333555-1", "email": "owners@company.tpl", "website": "http://company.tpl", "additionalData": [ { "label": "skype", "value": "companyOwner" } ] }, "accountManager": { "id": "57" }, "salesManager": { "id": "45" }, "isLead": false, "financials": { "tax": { "taxation": "domestic", "taxDisplay": "automatically", "useDeliveryThreshold": true, "taxNumber": "", "vatId": "" }, "paymentTerms": { "fixedPaymentTerms": false, "paymentTargetDays": 0, "paymentTargetDiscount": 0, "paymentTargetDiscountDays": 0 }, "paymentMethod": { "id": "32" }, "subscriptionPaymentMethod": "invoice", "customsInformation": "", "creditLimit": 0, "defaultCurrency": "EUR" }, "primaryBankAccount": { "bankName": "XYZ Bank", "owner": "Name of the owner", "iban": "DE89370400440532013000", "bic": "DEUTDEFFXXX", "sepa": { "companySepa": true, "mandateReference": "K21124DE60S21F2S09WX11G4FY", "mandateReferenceChange": false, "mandateReferenceDate": "2025-03-01", "usage": "recurring", "initial": true, "remark": "This is a comment" } }, "language": "EN", "commission": 9.9, "identifier": "MUI2", "logfile": "This is a log entry!!!!", "lat": 52.9979559, "lng": 11.7505879, "fromShop": { "id": "10" }, "marketing": { "marketingBan": false, "showBirthdayInCalendar": false, "birthdayCard": false, "ageApproval": false } } } } } } }, "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." } } } } } } ```