---
title: "🔒 Update customer V3"
method: PATCH
path: "/api/v3/customers/{id}"
tags: ["Customer"]
---

# 🔒 Update customer V3

`PATCH /api/v3/customers/{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: `customer:update`.

Update an existing customer.

## Path parameters

- `id` string, required

## Request body

- object
  - `number` string — Customer number
  - `deviatingDebtorAccountNumber` string — Deviating debtor account number for accounting
  - `mainProject` object — Main project the customer belongs to
    - `id` string, required — ID of the project
  - `primaryAddress` object — Primary address information for the customer
    - `name` string
    - `type` 'mrs' | 'mr' | 'company' | 'other'
    - `title` string
    - `contactPerson` string
    - `salutation` string
    - `department` string
    - `subDepartment` string
    - `addressSupplement` string
    - `street` string
    - `zipCode` string
    - `city` string
    - `state` string
    - `country` string
    - `gln` string
    - `email` string
    - `phone` string
    - `mobile` string
    - `fax` string
  - `deviatingBillingAddress` object — Deviating billing address information. Set to null to delete the deviating billing address.
    - `name` string
    - `type` 'mrs' | 'mr' | 'company' | 'other'
    - `title` string
    - `contactPerson` string
    - `salutation` string
    - `department` string
    - `subDepartment` string
    - `addressSupplement` string
    - `street` string
    - `zipCode` string
    - `city` string
    - `state` string
    - `country` string
    - `gln` string
    - `email` string
    - `phone` string
    - `mobile` string
    - `fax` string
  - `communication` object — Communication preferences and settings
    - `language` string — Language preference. The two-letter code of a language that exists in the system settings.
    - `website` string — Website URL
    - `allowTrackingEmails` boolean — Allow tracking emails
    - `allowFollowUpConfirmations` boolean — Allow follow-up confirmations
    - `allowMarketingEmails` boolean — Allow marketing emails
    - `additionalContactInformation` object[] — Additional contact information entries
      - `key` string, required — Contact information type/key
      - `value` string, required — Contact information value. Set to null to delete the entry.
  - `financials` object — Financial information and settings
    - `primaryBankAccount` object — Primary bank account information
      - `bankName` string — Bank name
      - `accountHolder` string — Account holder name
      - `iban` string — IBAN
      - `bic` string — BIC/SWIFT code
      - `sepa` object — SEPA mandate information
        - `isCompanySepa` boolean — Is company SEPA mandate
        - `mandateReference` string — SEPA mandate reference
        - `mandateReferenceChange` boolean — Mandate reference change flag
        - `mandateReferenceDate` string, date — Mandate reference date
        - `usage` 'single' | 'recurring' — SEPA mandate usage type
        - `isInitialMandate` boolean — Is initial mandate
        - `remark` string — SEPA mandate remark
    - `tax` object — Tax information
      - `vatId` string — VAT ID
      - `taxNumber` string — Tax number
      - `taxation` 'domestic' | 'eu' | 'export' | 'exempt' — Taxation type
      - `taxDisplay` 'automatically' | 'alwaysNet' | 'alwaysGross' — Tax display preference
      - `useDeliveryThreshold` boolean — Use delivery threshold
      - `customsInformation` string — Customs information
    - `paymentTerms` object — Payment terms configuration
      - `fixedPaymentTerms` boolean — Fixed payment terms
      - `paymentTargetDays` unknown
      - `paymentTargetDiscount` unknown
      - `paymentTargetDiscountDays` unknown
    - `paymentMethod` object — Payment method reference
      - `id` string, required — ID of the payment method
    - `supplierNumberForCustomer` string — Supplier number for customer
    - `subscriptionPaymentMethod` 'directDebit' | 'invoice' — Subscription payment method
    - `defaultCurrency` string — Default currency
    - `creditLimit` unknown
  - `fulfillment` object — Fulfillment and delivery settings
    - `shippingMethod` object — Shipping method reference
      - `id` string, required — ID of the shipping method
    - `freeShippingActive` boolean — Free shipping active
    - `freeShippingFrom` unknown
    - `ageCheckRequired` boolean — Age check required
    - `deliveryTerms` string — Delivery terms
    - `deliveryBlock` boolean — Delivery block
    - `deliveryBlockDate` string, date — Delivery block date
    - `deliveryBlockReason` string — Delivery block reason
    - `autoCreateDocuments` 'deliveryNote' | 'invoice' | 'deliveryNoteAndInvoice' — Auto create documents setting
    - `orderQuoteRemarks` string — Order quote remarks
    - `commissionConsignmentWarehouse` object — Consignment storage location
      - `id` string, required — ID of the storage location
  - `documentDelivery` object — Document delivery preferences
    - `invoiceAlwaysPaper` boolean — Invoice always paper
    - `amountInvoicePrints` integer — Amount of invoice prints
    - `preferFax` boolean — Prefer fax delivery
    - `documentRecipients` object — Document recipients configuration
      - `offer` object — Offer document recipients
        - `to` string — Primary email recipient
        - `cc` string[] — CC email recipients
      - `salesOrder` object — Sales order document recipients
        - `to` string — Primary email recipient
        - `cc` string[] — CC email recipients
      - `invoice` object — Invoice document recipients
        - `to` string — Primary email recipient
        - `cc` string[] — CC email recipients
      - `creditNote` object — Credit note document recipients
        - `to` string — Primary email recipient
        - `cc` string[] — CC email recipients
      - `deliveryNote` object — Delivery note document recipients
        - `to` string — Primary email recipient
        - `cc` string[] — CC email recipients
      - `purchaseOrder` object — Purchase order document recipients
        - `to` string — Primary email recipient
        - `cc` string[] — CC email recipients
      - `dunning` object — Dunning document recipients
        - `to` string — Primary email recipient
        - `cc` string[] — CC email recipients
  - `accountManager` object — Account manager reference
    - `id` string, required — ID of the address
  - `salesManager` object — Sales manager with commission
    - `id` string, required — Sales manager ID
    - `commission` unknown
  - `originSalesChannel` object — Origin sales channel reference
    - `id` string, required — ID of the sales channel
  - `groups` object[] — Groups the customer belongs to
    - `id` string, required — Group ID
  - `customerRoles` object[] — Customer roles associated with projects. All provided roles will be upserted.
    - `project` object — Project reference
      - `id` string, required — ID of the project
    - `validFrom` string, date — Valid from date
    - `expiresAt` string, date — Expires at date
  - `customFields` object[] — Custom fields for additional custom data
    - `key` string, required — Custom field key, Only customField1 through customField20 are allowed.
    - `label` string — Custom field label
    - `value` string, required — Custom field value
  - `notes` string — Notes for the customer
  - `tags` object[] — Tags to assign to the customer
    - `title` string, required — Title of the Tag

## Response `200`

Update an existing customer.

- object
  - `data` object — Customer entity
    - `id` string — ID of the customer
    - `createdAt` string, date-time — Creation timestamp
    - `updatedAt` string, date-time — Last update timestamp
    - `number` string — Customer number
    - `deviatingDebtorAccountNumber` string — Deviating customer number for accounting
    - `mainProject` object — Main project the customer belongs to
      - `id` string
    - `primaryAddress` object — Primary address information for the customer
      - `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
    - `deviatingBillingAddress` object — Deviating billing address information for the customer
      - `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
    - `communication` object — Communication preferences and settings for the customer
      - `language` string
      - `website` string
      - `allowTrackingEmails` boolean
      - `allowFollowUpConfirmations` boolean
      - `allowMarketingEmails` boolean
      - `additionalContactInformation` object[] — Additional contact information entries
        - `key` string
        - `value` string
    - `financials` object — Financial information and settings for the customer
      - `primaryBankAccount` object
        - `bankName` string — Masked by default. Requires customer:readBanking scope for unmasked value.
        - `accountHolder` string — Masked by default. Requires customer:readBanking scope for unmasked value.
        - `iban` string — Masked by default (e.g. DE89**************3000). Requires customer:readBanking scope for unmasked value.
        - `bic` string — Masked by default. Requires customer:readBanking scope for unmasked value.
        - `sepa` object
          - `isCompanySepa` boolean
          - `mandateReference` string — Masked by default. Requires customer:readBanking scope for unmasked value.
          - `mandateReferenceChange` boolean
          - `mandateReferenceDate` string
          - `usage` 'single' | 'recurring'
          - `isInitialMandate` boolean
          - `remark` string
      - `tax` object
        - `vatId` string
        - `taxNumber` string
        - `taxation` 'domestic' | 'eu' | 'export' | 'exempt'
        - `taxDisplay` 'automatically' | 'alwaysNet' | 'alwaysGross'
        - `useDeliveryThreshold` boolean
        - `customsInformation` string
      - `paymentTerms` object
        - `fixedPaymentTerms` boolean
        - `paymentTargetDays` integer
        - `paymentTargetDiscount` number, float
        - `paymentTargetDiscountDays` integer
      - `paymentMethod` object
        - `id` string
      - `supplierNumberForCustomer` string
      - `subscriptionPaymentMethod` 'directDebit' | 'invoice'
      - `defaultCurrency` string
      - `creditLimit` number, float
    - `fulfillment` object — Fulfillment and delivery settings for the customer
      - `shippingMethod` object
        - `id` string
      - `freeShippingActive` boolean
      - `freeShippingFrom` number, float
      - `ageCheckRequired` boolean
      - `deliveryTerms` string
      - `deliveryBlock` boolean
      - `deliveryBlockDate` string, date
      - `deliveryBlockReason` string
      - `autoCreateDocuments` 'deliveryNote' | 'invoice' | 'deliveryNoteAndInvoice'
      - `orderQuoteRemarks` string
      - `commissionConsignmentWarehouse` object
        - `id` string
    - `documentDelivery` object — Document delivery preferences for the customer
      - `invoiceAlwaysPaper` boolean
      - `amountInvoicePrints` unknown
      - `preferFax` boolean
      - `documentRecipients` object — Document recipients configuration for different document types
        - `offer` object
          - `to` string
          - `cc` string[]
        - `salesOrder` object
          - `to` string
          - `cc` string[]
        - `invoice` object
          - `to` string
          - `cc` string[]
        - `creditNote` object
          - `to` string
          - `cc` string[]
        - `deliveryNote` object
          - `to` string
          - `cc` string[]
        - `purchaseOrder` object
          - `to` string
          - `cc` string[]
        - `dunning` object
          - `to` string
          - `cc` string[]
    - `customerRoles` object[] — Projects associated with the customer as a customer role. When id is null, it means all projects in the system.
      - `project` object — Project associated with the customer
        - `id` string
      - `validFrom` string, date
      - `expiresAt` string, date
    - `groups` object[]
      - `id` string
    - `accountManager` object — Account manager responsible for the customer
      - `id` string
    - `salesManager` object — Sales manager responsible for the customer
      - `id` string
      - `commission` unknown
    - `originSalesChannel` object — Origin sales channel responsible for the customer
      - `id` string
    - `customFields` object[] — Custom fields with their values and metadata
      - `key` string
      - `value` string
      - `label` string
    - `notes` string — Notes added by the Customer
    - `deliveryAddresses` object[] — Delivery addresses associated with the customer
      - `id` string, required — Unique identifier for the delivery address
      - `type` 'company' | 'mrs' | 'mr' | 'other', required — Type of the delivery address recipient. Use 'company' for business addresses, 'mrs' for female recipients, 'mr' for male recipients, and 'other' for other types.
      - `name` string, required — Full name of the delivery address recipient. For companies, this is the company name. For persons, this is the full name.
      - `title` string — Title of the contact person.
      - `contactPerson` string — Name of the contact person at this delivery address. This is typically used for company addresses to specify who should receive the delivery.
      - `salutation` string — Salutation or greeting phrase for the delivery address. Can be used for personalized communication.
      - `department` string — Department name at the delivery address. Useful for routing deliveries within larger organizations.
      - `subDepartment` string — Sub department name at the delivery address. Useful for routing deliveries within larger organizations.
      - `addressSupplement` string — Additional address information such as building name, floor, hall, or specific delivery instructions for the location
      - `street` string, required — Street name and house number of the delivery address
      - `zipCode` string, required — Postal code (ZIP code) of the delivery address
      - `city` string, required — City name of the delivery address
      - `state` string — State or region code in ISO 3166-2 format (without country prefix). Required for countries with states/provinces.
      - `country` string, required — Country code in ISO 3166-1 alpha-2 format
      - `gln` string — Global Location Number (GLN) - a 13-digit number used to uniquely identify physical locations or legal entities globally. Used in supply chain and logistics for automated identification.
      - `phone` string — Primary phone number for the delivery address. Used for delivery coordination and communication.
      - `mobile` string — Mobile phone number for the delivery address contact. Useful for urgent delivery notifications.
      - `fax` string — Fax number for the delivery address. Still used by some organizations for official communications.
      - `email` string, email — Email address for delivery notifications and communication
      - `deliveryDetails` object, required — Delivery-specific settings and information for the address
        - `taxType` 'domestic' | 'eu' | 'export' | 'exempt' — Tax classification for deliveries to this address. 'domestic' for same-country deliveries, 'eu' for EU cross-border, 'export' for non-EU international, 'exempt' for tax-exempt deliveries.
        - `defaultDeliveryAddress` boolean — Indicates whether this is the default delivery address. Only one delivery address per customer/supplier should be set as default.
        - `termsOfDelivery` string — Incoterms or delivery terms code (e.g., EXW, FOB, CIF, DAP). Defines the responsibilities and costs between buyer and seller during shipping.
        - `vatId` string — VAT identification number for this delivery address. May differ from the main VAT ID for multi-location businesses.
        - `remark` string — Internal notes about this delivery address. Not visible externally. Used for operational information like opening hours, special handling instructions, or access codes.
        - `note` string — Public notes or delivery instructions for this address. May be shared with carriers or printed on delivery documents.
    - `contactPersons` object[] — Contact persons associated with the customer
      - `id` string — ID of contact person
      - `type` 'mrs' | 'mr' | 'company' | 'other' — Type of contact person
      - `name` string — Name of contact person
      - `title` string — Title of contact person
      - `salutation` string — Salutation of contact person
      - `department` string — Department of contact person
      - `subDepartment` string — Sub-Department of contact person
      - `street` string — Street of contact person address
      - `addressSupplement` string — Address supplement of contact person address
      - `zipCode` string — Zip code of contact person address
      - `city` string — City of contact person address
      - `country` string — Country of contact person address
      - `state` string — State of contact person address
      - `phone` string — Phone number of contact person
      - `mobile` string — Mobile number of contact person
      - `fax` string — Fax number of contact person
      - `email` string — Email address of contact person
      - `contactPersonDetails` object — Contact person details
        - `position` string
        - `birthday` string, date
        - `language` string
        - `allowMarketingEmails` boolean
        - `internalNote` string
        - `remarks` string
      - `groups` object[] — Group information
        - `id` string — ID of group
      - `createdAt` string, date-time — Creation timestamp
      - `updatedAt` string, date-time — Last update timestamp
    - `tags` object[] — Tags assigned to the customer
      - `id` string
      - `title` string

## Other responses

- `400` — Failed validation
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `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/versions/8a27ba392442/schema)