accounts - User accounts - WEBSALE Dokumentation

The accounts configuration node contains all the settings required for managing user accounts in the online shop. It defines how customers register, log in and stay logged in, and which data they can view or edit in their customer account. In addition, it contains security-relevant parameters such as password checks, login blocks, auto-login rules, and the management of payment and address data. This configuration lets you tailor the behaviour of the customer account to the requirements of your shop — from a simple sign-in to fine-grained control of permissions and data fields.

`accounts*` - Basic structure

The basic structure of the accounts node is shown below:

{
    "accounts": {
      "account": {...},
      "accountRestrictions": {...},
      "addressFieldsSettings":{...},
      "addressField":{...},
      "autoLogin": {...},
      "bankInfoField": {...},
      "creditCardField": {...},
      "customAddressField": {...},
      "watchListField": {...}
    }
}

Parameter descriptions

Parameter	Description
`account`	Controls the central account settings for customers, e.g. security checks, password rules and login protection mechanisms.
`accountRestrictions`	Restricts the availability of customer accounts to defined subshops.
`addressFieldsSettings`	Controls cross-cutting configurations for address fields, e.g. custom labels, default values and read-only rules.
`addressField`	Defines the structure and validation rules for individual address fields.
`autoLogin`	Controls the “stay signed in” behaviour for customer accounts, including expiration times and action permissions.
`bankInfoField`	Enables recording and managing bank details in the customer account.
`creditCardField`	Configures the display of pseudonymised credit card data in the customer account.
`customAddressField`	Allows you to define additional custom address fields for billing and delivery addresses.
`watchListField`	Defines fields of the watchlist or wish list with a unique ID and name. These fields can only be addressed via the API and have no configuration option in the Admin Interface.

`accounts.account` - User account

Controls the central account settings for customers. Here you define security checks, password rules, login protection mechanisms and other account functions. This configuration influences how customer accounts are created, used to sign in and managed in the shop. The settings for this section can be found in the Admin Interface under .

Example configuration for all subshops (`accounts.account`)

{
  "accountActivation": {
    "enabled": true,
    "requireOptIn": true
  },
  "additionalPasswordCheckLevels": [
    {
      "checks": [
        {
          "options": { "len": 8 },
          "service": "dataChecker.minLength"
        }
      ]
    },
    {
      "checks": [
        {
          "options": { "minChars": 1 },
          "service": "dataChecker.digitClass"
        },
        {
          "options": { "minChars": 1 },
          "service": "dataChecker.specialClass"
        }
      ]
    }
  ],
  "confirmationOfRegistrationEmail": {
    "fromAddress": "",
    "fromName": "",
    "subject": "",
    "template": ""
  },
  "duplicate": {
    "checkExistence": false,
    "keepAccount": true,
    "foundEmail": {
      "template": "",
      "subject": "",
      "fromAddress": "",
      "fromName": ""
    },
    "informFullAddress": true,
    "keepSignsInInformAddress": 3
  },
  "errorCodes": {
    "passwordResetRequired": "<Textbaustein>"
  },
  "login": {
    "ipBlockCount": 3,
    "ipBlockCountDuration": 1,
    "ipBlockDuration": 10,
    "ipBlockEnabled": true,
    "loginBlockCount": 5,
    "loginBlockDuration": 180,
    "loginBlockEmail": {
      "fromAddress": "noreply@websale.de",
      "fromName": "Mein Onlineshop",
      "subject": "Mein Onlineshop | Ihr Login wurde gesperrt",
      "template": "loginBlocked.htm"
    },
    "loginCountDuration": 60
  },
  "newCustomerRules": [
    {
      "field": "customerNumber",
      "type": "filled"
    }
  ],
  "passwordChecks": [
    {
      "options": { "len": 64 },
      "service": "dataChecker.maxLength"
    }
  ],
  "saveCreditCardData": false,
  "sendConfirmationOfRegistrationEmail": true,
  "subAccountsEnabled": false
}

Parameter descriptions

Parameter	Type	Description
`accountActivation`	object	Configuration for existing customer registration. Allows a customer record already stored in the shop (e.g. via import) to be activated using the AccountActivate action. The account is considered not yet activated if no password has been set, no employee accounts are assigned to it, or no invitation link has been sent yet. For security reasons, activation can only be carried out once. Which fields are requested during existing customer registration is controlled here.
`enabled`	bool	Enables (`true`) or disables (`false`) the existing customer registration.
`requireOptIn`	bool	Controls whether an opt-in email is sent to the stored address after activation, which has to confirm the registration. Default: `true`
`additionalPasswordCheckLevels`	list	Additional checks for passwords. Enables tiered security requirements, such as minimum length or specific character groups (digits, special characters).
`checks`	multiService	List of check rules within one level; all included checks must be satisfied.
`service`	string	Check type (e.g. `dataChecker.minLength`, `dataChecker.maxLength`, `dataChecker.digitClass`, `dataChecker.specialClass`).
`options`	array	Options object for the respective check type. More information about the validation and check services is available here.
`confirmationOfRegistrationEmail`	object	Configuration of the registration confirmation email. Only used if `sendConfirmationOfRegistrationEmail` = `true`. The email may, for example, include an option to cancel the request via a link.
`fromAddress`	string	Sender address used when sending the email.
`fromName`	string	Display name of the sender in the email.
`subject`	string	Subject line of the registration confirmation email.
`template`	string	Name or path of the email template to be used.
`duplicate`	object	Collection object for all settings of the duplicate check during registration.
`checkExistence`	bool	Enables (`true`) or disables (`false`) the duplicate check. Default: `false`
`keepAccount`	bool	Determines whether the account is still created even if the check finds a duplicate (`true` = create anyway).
`foundEmail`	object	Email configuration for sending to the found duplicate(s). In the email template, `$wsRequestVariables.email` can be used to output the email address entered during registration — for example so that the account admin can create a subaccount for the user.
`template`	string	Name or path of the email template.
`subject`	string	Subject line of the email.
`fromAddress`	string	Sender address of the email.
`fromName`	string	Display name of the sender.
`informFullAddress`	bool	Controls whether the found duplicate email address is shown uncensored (`true`) or censored (`false`) in the error details of the `duplicateAccountFound` message (action `accountRegister`).
`keepSignsInInformAddress`	int	Only effective if `informFullAddress` = `false`: number of characters in the local part of the email address (everything before the `@`) that are kept. All other characters are replaced with `*`.
`passwordChecks`	array	Base password checks (always applied). The structure is identical to `additionalPasswordCheckLevels`.
`service`	string	Check type (e.g. `addressCheck.minLength`, `dataChecker.minLength` to check for a minimum value, `addressCheck.maxLength`, `dataChecker.maxLength` to check the maximum number of characters, etc.). An overview of the available validation and check rules for address data fields can be found here.
`options`	array	Options object for the respective check type.
`errorCodes`	array	Collection object for special error states.
`passwordResetRequired`	string	Key/code that is returned if a password reset is required for the user account (e.g. after an administrative reset or for security reasons). Provided by the system and cannot be changed.
`login`	array	Settings for sign-in protection mechanisms.
`ipBlockEnabled`	bool	Enables (`true`) / disables (`false`) the IP-based block.
`ipBlockCount`	int	Number of failed attempts per IP before the IP is blocked. Default: 10
`ipBlockCountDuration`	int	Time window in minutes during which IP attempts are counted. Default: 1
`ipBlockDuration`	int	Block duration of the IP in minutes.
`loginBlockCount`	int	Number of failed logins per account before the account is blocked. Default: 5
`loginCountDuration`	int	Time window in minutes during which account attempts are counted. Default: 60
`loginBlockDuration`	int	Account block duration in minutes. Default: 180
`loginBlockEmail`	array	Email notification when an account is blocked.
`fromAddress`	string	Sender address (email).
`fromName`	string	Display name of the sender.
`subject`	string	Subject of the email.
`template`	string	Template name/file (e.g. `loginBlocked.htm`).
`newCustomerRules`	array	Rules by which a logged-in customer is classified as a new customer (`newCustomer`) during the order process — for example, to block payment methods for new customers. See New customer rules for details. With `null` or an empty list, no logged-in customer is treated as a new customer.
`saveCreditCardData`	bool	Allow storing credit card data in the account (`true`/`false`).
`sendConfirmationOfRegistrationEmail`	bool	Indicates whether a confirmation email is sent automatically after registration.
`subAccountsEnabled`	bool	Enables or disables (`true`/`false`) the employee accounts feature. If the feature is active, individual employee accounts can be created for each parent account. Once this feature is enabled, signing in directly to the parent account is no longer possible. For this reason, activation should only take place in a newly set up shop — a later activation will prevent existing users from being able to sign in.

New customer rules (`newCustomerRules`)

newCustomerRules defines when a logged-in customer is considered a new customer during the order process. The customer type newCustomer determined this way is evaluated by the payment method validation paymentValidation.accountType — for example, to block purchase on invoice for new customers. Each rule consists of a field and a condition. If the condition of a rule applies, the customer is not considered a new customer. Only when none of the rules applies is the customer classified as a new customer.

Example configuration (`accounts.account.newCustomerRules`)

A customer counts as a new customer as long as no customer number has been assigned yet:

{
  "newCustomerRules": [
    {
      "field": "customerNumber",
      "type": "filled"
    }
  ]
}

Parameter overview

Parameter	Type	Description
`field`	string	The field used for the check. Special case `"customerNumber"`: the customer number of the user account. All other values are interpreted as the `dataId` of a field of the billing address (standard or additional address fields). The value is not validated against existing fields — a non-existent field always yields an empty value.
`type`	enum	Condition under which the customer is not considered a new customer. Possible values: - `"filled"` — if the field is filled, the customer is not considered a new customer. - `"empty"` — if the field is empty, the customer is not considered a new customer. Default: `"filled"`

The customer type is determined during the login within the order process based on these rules (newCustomer or customer). A new registration during the order process always leads to the customer type newCustomer, regardless of the rules. Guest orderers have the customer type guest.

`accounts.accountRestrictions` - Subshop restrictions for user accounts

Restricts the availability of customer accounts to defined subshops, for example to make B2B accounts available only in a country-specific shop, or to provide exclusive areas per tenant or region. The settings for this section can be found in the Admin Interface under .

Example configuration for all subshops (`accounts.accountRestrictions`)

{
  "subshopRestrictionList": [],
  "subshopRestrictionsEnabled": false,
  "subshopRestrictionsFallback": "onlySelf"
}

Parameter descriptions

Parameter	Type	Description
`subshopRestrictionsEnabled`	bool	Enables (`true`) or disables (`false`) the subshop restrictions for customer accounts.
`subshopRestrictionsFallback`	enum	Fallback behaviour when no explicit assignment applies (e.g. empty list or missing identifier). Default: `onlySelf` — the account can only be used in the “own / currently addressed” subshop.
`subshopRestrictionList`	list	List of allowed subshops (allowlist) for the account. Entries must match the subshop identifiers used in your environment (e.g. the keys in the subshop configuration). If the list is empty, the behaviour from `subshopRestrictionsFallback` applies.

`accounts.addressFieldsSettings` - Custom address field settings

Controls the central configuration of address fields in the shop. Here you can define custom labels, default values, visibility and read-only rules for billing and delivery addresses. The settings for this section can be found in the Admin Interface under .

Example configuration for all subshops (`accounts.addressFieldsSettings`)

{
  "customLabelsDefinition": [],
  "defaultValuesDefinition": [],
  "inputVisibilityDefinition": null,
  "readOnlyFields": null
}

Parameter overview

Parameter	Type	Description
`customLabelsDefinition`	list	Definition of condition-dependent field labels for address fields.
`defaultValuesDefinition`	list	Defines condition-dependent default values / pre-fills for address fields.
`inputVisibilityDefinition`	list	Defines the visibility of individual address fields.
`readOnlyFields`	list	Defines which address fields are only visible and not editable.

Condition-dependent definitions (customLabelsDefinition & defaultValuesDefinition) The definitions defaultValuesDefinition and customLabelsDefinition allow you to define default values and custom field labels for address fields based on certain conditions. Both definitions follow the same structure and support a conditions array that can be used to tie the application of the rule to field conditions. Structure of an entry

Property	Type	Description
`fields`	list	List of affected address fields (e.g. `accounts.addressField.firstName`).
`addressType`	string	Address type the rule applies to. `"bill"` = billing address, `"delivery"` = delivery address.
`label` / `value`	string	This distinguishes between the two definitions. `customLabelsDefinition` (`label`): the label to be displayed. `defaultValuesDefinition` (`value`): the default value to pre-fill.
`conditions`	list	List of conditions that must all be satisfied for the rule to apply.

Structure of a condition

Property	Type	Description
`field`	string	The address field the condition refers to (e.g. `accounts.addressField.country`).
`type`	string	Type of check. `value`: exact comparison value, or `filled`: field is filled.
`value`	string	Depends on what is defined for `type`. For `"value"`: the expected value (e.g. `"DE"`). For `"filled"`: an empty string (`""`).

Example for customLabelsDefinition Custom field labels that are displayed depending on conditions.

{
  "customLabelsDefinition": [
    {
      "fields": ["accounts.addressField.firstName"],
      "addressType": "bill",
      "label": "Vorname (Rechnung)",
      "conditions": [
        {
          "field": "accounts.addressField.country",
          "type": "value",
          "value": "DE"
        }
      ]
    },
    {
      "fields": ["accounts.addressField.firma"],
      "addressType": "delivery",
      "label": "Firma (Lieferung)",
      "conditions": [
        {
          "field": "accounts.addressField.country",
          "type": "filled",
          "value": ""
        }
      ]
    }
  ]
}

Explanation In the first entry, the accounts.addressField.firstName field in the billing address is labelled “Vorname (Rechnung)” — but only if the country is set to DE. In the second entry, the accounts.addressField.firma field in the delivery address gets the label “Firma (Lieferung)” as soon as the accounts.addressField.country field contains any value (type: "filled"). Example for defaultValuesDefinition Default values for address fields, also pre-filled based on conditions.

{
  "defaultValuesDefinition": [
    {
      "fields": ["accounts.addressField.country"],
      "addressType": "bill",
      "value": "DE",
      "conditions": []
    },
    {
      "fields": ["accounts.addressField.salutation"],
      "addressType": "delivery",
      "value": "Herr",
      "conditions": [
        {
          "field": "accounts.addressField.country",
          "type": "value",
          "value": "DE"
        }
      ]
    }
  ]
}

Explanation In the first entry, the accounts.addressField.country field in the billing address is unconditionally pre-filled with "DE". In the second entry, the salutation of the delivery address (accounts.addressField.salutation) is set to "Herr" only when the country is DE.

`accounts.addressField` - Define individual address fields

Controls the structure and properties of individual address fields in the shop. Validations allow inputs to be checked and formal requirements (e.g. required fields, format checks) to be defined. The settings for this section can be found in the Admin Interface under .

Example configuration for all subshops (`accounts.addressField.firstName`)

{
  "label": "<Textbaustein>",
  "name": "firstName",
  "validations": [
    {
      "options": {
        "len": 255
      },
      "service": "addressCheck.maxLength"
    }
  ]
}

Parameter overview

Parameter	Type	Description
`label`	string	Definition of the field label.
`name`	string	Display name (in this example of the customer; in other cases, for example, the name of the city in which the customer lives).
`validations`	array	Defines the list of validation rules that are applied to the respective address field.
`options`	array	Defines the parameters or settings that a validation rule requires — e.g. limits, allowed characters or conditions.
`len`	int	In the example, specifies the maximum permitted character length for the validation.
`service`	string	Designates the validation service used to perform the actual check — here, for example, `addressCheck.maxLength` to control the maximum field length.

`accounts.autoLogin` - Stay signed in

Controls the “stay signed in” behaviour (auto-login) for customer accounts: activation, expiration times and reactions to special cases. The settings for this section can be found in the Admin Interface under .

Example configuration for all subshops (`accounts.autoLogin`)

{
  "actions": null,
  "active": true,
  "errorCodes": {
    "actionRequiresLogin": ""
  },
  "expireTimesInDays": {
    "cookie": 30,
    "noAutoLogin": 10,
    "noPasswordLogin": 20
  },
  "restriction": "notAllowed"
}

Parameter description

Parameter	Type	Description
`active`	bool	Enables (`true`) or disables (`false`) the auto-login function as a whole.
`restriction`	enum	Policy for auto-login. Value `notAllowed`: auto-login is not permitted (no persistent session). Other values are predefined by the system.
`expireTimesInDays`	object	Collection object with expiration times (in days) for different scenarios.
`cookie`	uint	Validity period of the auto-login cookie in days. After expiration, a regular login is required. Default: 30
`noAutoLogin`	uint	Maximum inactivity period in days without auto-login; after expiration, no further automatic sign-in is attempted. Default: 10
`noPasswordLogin`	uint	Period in days after which a password input is enforced despite an existing auto-login (e.g. as re-authentication). Default: 20
`errorCodes`	object	Object for special error states.
`actionRequiresLogin`	string	Key/code for the case where an action requires a new sign-in.
`actions`	list	List of actions that are allowed during an automatic login without an additional password prompt. This lets you specify exactly what customers may use while signed in without having to sign in again. For example, you can grant access to non-critical functions such as the watchlist, while security-relevant actions (e.g. basket or order processes) still require a renewed sign-in. Examples of allowed actions: `WatchListAdd` → create a new watchlist, `WatchListDelete` → delete a watchlist, `WatchListItemAdd` → add products to a watchlist, `WatchListItemDelete` → remove products from a watchlist. If no actions should be allowed, the value must be set to `null`. In this case, all actions are automatically blocked and a new sign-in is required for every interaction.

`accounts.bankInfoField` - Bank details

Allows recording and managing bank details in the customer account. Unlike credit card data, this information can be entered, changed and stored directly in the shop. The stored bank details are then available for selection during the order process — in particular for the SEPA direct debit payment method.

Example configuration for all subshops (`accounts.bankInfoField.owner`)

{
  "dataId": "owner",
  "label": "Kontoinhaber",
  "name": "owner"
}

Parameter description

Parameter	Type	Description
`dataId`	string	Internal identifier of the data field (e.g. “owner”).
`label`	string	Display name in the customer account, e.g. “Account holder”.
`name`	string	Technical field name. Predefined by the system and should not be changed. The following `name` values are available: `accountNumber` — account number of the customer (usually only relevant for older accounts without IBAN), `bankCode` — bank sort code (only relevant if no IBAN is used), `bankName` — name of the bank, `bic` — BIC (Business Identifier Code) of the bank, `iban` — IBAN (International Bank Account Number) of the account holder, `owner` — name of the account holder, `sepaDebitType` — type of SEPA direct debit (e.g. CORE or B2B), `sepaDirectDebitMandate` — mandate reference number of the SEPA direct debit, `sepaMandateDate` — date the mandate was granted (ISO format recommended: YYYY-MM-DD), `sepaMandateType` — type of the SEPA mandate (e.g. initial mandate or follow-up mandate).

`accounts.creditCardField` - Credit cards

For security reasons, payment by credit card is handled exclusively through external Payment Service Providers (PSP). Entering credit card data, detecting the card type and carrying out the 3D Secure 2.0 procedure all take place entirely at the payment provider. Real credit card data is never stored or processed in the online shop. In the customer account, pseudonymised credit card information can be displayed — provided this is supported by the PSP and contractually enabled. This allows customers to conveniently choose a stored card the next time they make a purchase without having to enter the data again. Entering or changing credit card data directly in the shop is not possible.

Example configuration for all subshops (`accounts.creditCardField.holder`)

{
  "dataId": "holder",
  "label": "Kreditkarten-Inhaber",
  "name": "holder"
}

Parameter description

Parameter	Type	Description
`dataId`	string	Internal identifier of the data field (e.g. “holder”).
`label`	string	Display name in the customer account, e.g. “Credit card holder”.
`name`	string	Technical field name. Predefined by the system and should not be changed. The following `name` values are available: `cvCode` — security code (3 or 4 digits, depending on the card type), `expireMonth` — expiration month of the card, `expireYear` — expiration year of the card, `holder` — card holder, `number` — card number (pseudonymised), `type` — card type (e.g. Visa, MasterCard, American Express).

`accounts.customAddressField` - Additional address data fields

Allows you to define additional address fields for billing and/or delivery addresses. These fields supplement the standard entries (e.g. name, street, postal code, city, country, telephone) with custom input fields that are displayed and stored in the customer account or during checkout. Examples of typical additional fields are: address supplement, floor, PO box, packing station number or department.

Example configuration for all subshops (`accounts.customAddressField.postOfficeBox`)

{
  "dataId": "customField.postfach",
  "label": "<Textbaustein>",
  "name": "postfach",
  "validations": [
    {
      "options": {
        "len": 3
      },
      "service": "addressCheck.minLength"
    },
    {
      "options": {
        "len": 20
      },
      "service": "addressCheck.maxLength"
    },
    { 
      "options": {
        "signs": "^[0-9A-Za-z\\s-]+$"
      },
      "service": "addressCheck.legalSigns" 
    }   
  ]
}

Parameter description

Parameter	Type	Description
`dataId`	string	Internal identifier or reference ID of the field (e.g. for linking to external systems or data sources).
`label`	string	Display name of the field in the frontend (e.g. “Floor” or “Packing station number”).
`name`	string	Technical field name used internally for storage and assignment.
`validations`	array	Optional validation object to check the input (e.g. required field, maximum length, specific character formats). Can be `null` if no validation is required. An overview of the available validation and check rules for address data fields can be found here.

`accounts.watchListField` - Watchlist

Defines fields of the watchlist or wish list with a unique ID and name. These fields can only be addressed via the API and have no configuration option in the Admin Interface.

Example configuration for all subshops (`accounts.watchListField`)

{
  "name": "watchListIds"
}

Parameter description

Parameter	Type	Description
`name`	string	Technical name of the watchlist field. Used for uniquely identifying the field within the API and internal processes.

​accounts* - Basic structure

​Parameter descriptions

​accounts.account - User account

​Example configuration for all subshops (accounts.account)

​Parameter descriptions

​New customer rules (newCustomerRules)

​Example configuration (accounts.account.newCustomerRules)

​Parameter overview

​accounts.accountRestrictions - Subshop restrictions for user accounts

​Example configuration for all subshops (accounts.accountRestrictions)

​Parameter descriptions

​accounts.addressFieldsSettings - Custom address field settings

​Example configuration for all subshops (accounts.addressFieldsSettings)

​Parameter overview

​accounts.addressField - Define individual address fields

​Example configuration for all subshops (accounts.addressField.firstName)

​Parameter overview

​accounts.autoLogin - Stay signed in

​Example configuration for all subshops (accounts.autoLogin)

​Parameter description

​accounts.bankInfoField - Bank details

​Example configuration for all subshops (accounts.bankInfoField.owner)

​Parameter description

​accounts.creditCardField - Credit cards

​Example configuration for all subshops (accounts.creditCardField.holder)

​Parameter description

​accounts.customAddressField - Additional address data fields

​Example configuration for all subshops (accounts.customAddressField.postOfficeBox)

​Parameter description

​accounts.watchListField - Watchlist

​Example configuration for all subshops (accounts.watchListField)

​Parameter description

`accounts*` - Basic structure

Parameter descriptions

`accounts.account` - User account

Example configuration for all subshops (`accounts.account`)

Parameter descriptions

New customer rules (`newCustomerRules`)

Example configuration (`accounts.account.newCustomerRules`)

Parameter overview

`accounts.accountRestrictions` - Subshop restrictions for user accounts

Example configuration for all subshops (`accounts.accountRestrictions`)

Parameter descriptions

`accounts.addressFieldsSettings` - Custom address field settings

Example configuration for all subshops (`accounts.addressFieldsSettings`)

Parameter overview

`accounts.addressField` - Define individual address fields

Example configuration for all subshops (`accounts.addressField.firstName`)

Parameter overview

`accounts.autoLogin` - Stay signed in

Example configuration for all subshops (`accounts.autoLogin`)

Parameter description

`accounts.bankInfoField` - Bank details

Example configuration for all subshops (`accounts.bankInfoField.owner`)

Parameter description

`accounts.creditCardField` - Credit cards

Example configuration for all subshops (`accounts.creditCardField.holder`)

Parameter description

`accounts.customAddressField` - Additional address data fields

Example configuration for all subshops (`accounts.customAddressField.postOfficeBox`)

Parameter description

`accounts.watchListField` - Watchlist

Example configuration for all subshops (`accounts.watchListField`)

Parameter description