customer - Customer data

The customer node configures capture of customer data: address fields, required entries, field groups, validation and storage in the account or order.

The customer configuration node bundles all settings around capturing and processing customer data in the online shop.
It defines which information is requested in the customer account and during checkout, how these fields are named, grouped, validated and marked as required — including control of the storage type (in the account, in the order or both).
In addition, it allows you to structure forms via field groups as well as set global display and storage rules for additional customer data fields.

​

customer* - Basic structure

The basic structure of the customer node is shown below:

{
    "customer": {
      "customerDataField": {...},
      "customerDataFieldSettings": {...},
      "customerDataGroup": {...}
    }
}

​

Parameter overview

Parameter	Description
customer	Manages customer data and account functions in the shop.
customerDataField	Configurable customer data field.
customerDataFieldSettings	Settings for the display and storage of customer data fields.
customerDataGroup	Groups several customer data fields into a section.

​

customer.customerDataField - Customer data fields

Defines freely configurable fields for customer data — including label, required status and storage location. Supports various field types (text, number with units, date, checkbox, selection) with defaults, value ranges and validations.

​

Example configuration

{
  "name": "companyName",
  "label": "<Textbaustein>",
  "required": true,
  "uniqueValue": false,
  "storageStrategy": "account",
  "type": {
    "text": {
      "default": ""
    }
  },
  "validations": [
    { "service": "dataChecker.minLength", "options": { "len": 2 } },
    { "service": "dataChecker.maxLength", "options": { "len": 80 } }
  ]
}

​

Parameter overview

Parameter	Type	Description
name	string (unique)	Technical name of the field. Must be unique and is chosen by you.
label	string	Display name on the user interface.
required	bool	Marks the field as required. Default: false
uniqueValue	bool	Defines whether the value of the field must be unique across the shop (true). If the option is active, the field is used in the duplicate check (accounts.account → duplicate, see accounts - User accounts) — for example for the VAT ID. Default: false
accountMemberField	bool	Determines whether the field is stored on the company account or on employee accounts.
storageStrategy	enum	Storage location of the values — in the account, only in the order or both. Possible values: - account - order - hybrid Default: account
type	oneOf	Field type for detailed configuration.
text	object	Text input field.
default	string	Pre-fill for the text field. (optional)
number	object	Numeric input field.
default	int	Pre-fill for the input field (optional).
min	int	Minimum allowed value. (optional)
max	int	Maximum allowed value. (optional)
step	int	Step size of the value during input. Default: 1
numDecimals	int	Number of decimal places. Default: 0
unit	oneOf	Unit definition (optional).
constant	object	Fixed, non-modifiable unit.
name	string	Technical name of the unit.
label	string	Display label of the unit.
dynamic	object	Base unit + selectable unit.
baseUnitName	string	Name of the base unit.
unitOptions	list (object)	List of available units.
name	string	Technical name of the unit.
label	string	Display label of the unit.
factor	float	Conversion factor.
converter	singleService	Service for converting the value when the unit changes (optional). Currently only unitConverter.orderOfMagnitude is available here. It converts using the factors from unitOptions. Without an entry, the value remains unchanged when the unit changes. More under Validation and check services
freeSelection	object	Free selection from fixed options.
unitOptions	list (object)	Selectable units.
name	string	Technical name.
label	string	Display label.
defaultOptionName	string	Default unit.
date	object	Date field.
default	string	Pre-fill (optional).
checkbox	object	Checkbox.
default	bool	Pre-fill for the checkbox. Default: false
select	object	Selection list (dropdown).
options	list (object)	Available selection values.
value	string	Technical value of an option.
label	string	Display label of the option.
default	string	Pre-selected option (optional).
validations	multiService	List of validation rules. Examples: - minLength - maxLength - more under Validation and check services. Target: dataChecker

​

customer.customerDataFieldSettings - Field configuration

Controls how additional customer data fields are displayed and stored in the shop. Ungrouped fields can optionally be shown, and account fields can additionally be stored in the order. In addition, you define here which fields are requested during new or existing customer registration.

​

Example configuration

{
  "showUngroupedFields": true,
  "storeAccountFieldsInOrder": false,
  "newCustomerFields": [
    "customer.customerDataField.neukundenfeld1",
    "customer.customerDataField.neukundenfeld2"
  ],
  "existingCustomerFields": [
    "customer.customerDataField.bestandskundenfeld1",
    "customer.customerDataField.bestandsfeld2"
  ]
}

​

Parameter overview

Parameter	Type	Description
showUngroupedFields	bool	Shows ungrouped customer data fields in the form. Default: true
storeAccountFieldsInOrder	bool	Stores account fields additionally in the order. Default: false
newCustomerFields	multiAssoc	List of customer data fields requested during new customer registration. Target: customer.customerDataField
existingCustomerFields	multiAssoc	List of customer data fields requested during existing customer registration. Target: customer.customerDataField

​

customer.customerDataGroup - Grouping

Groups freely defined customer data fields into a section (e.g. billing address, company information). Each group has a technical name, a visible label and references the contained fields.

​

Example configuration

{
  "name": "company_data",
  "label": "<Textbaustein>",
  "fields": [
    "customer.customerDataField.company",
    "customer.customerDataField.vatId",
    "customer.customerDataField.phone"
  ]
}

​

Parameter overview

Parameter	Type	Description
name	string	Technical name of the group. Chosen by you.
label	string	Display name of the group in the form.
fields	multiAssoc	List of assigned customer data fields shown in this group. Target: customer.customerDataField