> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# API reference customer data
> Create, update, export, and delete customer accounts, addresses, and bank details through the Admin Interface API customer data endpoints.
The `customerAccounts/` endpoint provides a REST interface for managing customer data in the shop system. The API enables creating, retrieving, updating, and deleting customer accounts, addresses, and bank details. Additionally, data can be exported or password resets initiated. All endpoints are designed to enable systematic management and maintenance of customer data beyond the admin interface.
***
## Supported methods
List of all supported methods.
| **Command/info** | **Endpoints** | **GET** | **POST** | **PUT** | **DELETE** |
| ----------------- | ---------------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **Customer data** | customerAccounts/ | | | | |
| **Addresses** | customerAccounts/…/addresses | | | | |
| **Bank data** | customerAccounts/…/bankData | | | | |
| **Bulk queries** | bulk/ | | | | |
## Data fields
### Data fields of a customer account
| **Name** | **Type** | **Meaning** |
| ------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **allSubshopsAllowed** | Boolean | Indicates whether the customer is enabled for all subshops |
| **allowedSubshopIds** | String\[] | List of subshops for which the customer is enabled |
| **blockedPaymentMethods** | String\[] | List of payment method filters that are blocked for this account. Blocked payment methods are not available to the account itself or to its member accounts.
Each entry may contain the wildcard `*`, a leading `!` negates the pattern (e.g. `["*", "!invoice"]` = block all payment methods except `invoice`) |
| **createdAt** | String | Time of account creation (ISO 8601 format, UTC) |
| **customerNumber** | String | Customer number assigned by the system or externally |
| **deleted** | Boolean | Indicates whether the account has been deleted |
| **displayName** | String | Display name of the customer (shown e.g. with comments or reviews) |
| **email** | String | Email address of the customer |
| **enabledPaymentMethods** | String\[] | List of payment method filters that are specifically enabled for this account. Relevant for payment methods configured with `availableByDefault: false`, which are therefore not available by default (see [Configuration payment methods](/en/konfiguration/payment-zahlungsmethoden)).
Wildcard `*` and negation via `!` are supported as with `blockedPaymentMethods` |
| **id** | Integer | Internal unique ID of the customer |
| **loginBlocked** | Boolean | Indicates whether login is blocked for this account |
| **mainSubshop** | String | Main subshop |
| **meta.currentLogin** | String | Time of the current login (ISO 8601 format, UTC) |
| **meta.dataSets.accountBasketId** | String | The basket ID associated with the customer account |
| **meta.dataSets.lastUsedBillAddressId** | Integer | ID of the most recently used billing address |
| **meta.dataSets.lastUsedDeliveryAddressId** | Integer | ID of the most recently used delivery address |
| **meta.dataSets.lastUsedPaymentMethodId** | String | ID of the most recently used payment method |
| **meta.dataSets.lastUsedPseudoCCId** | String | ID via which credit card data was last found |
| **meta.dataSets.lastUsedShippingMethodId** | String | ID of the most recently used shipping method |
| **meta.dataSets.mainAddressId** | Integer | ID of the customer's main address |
| **meta.emailVerificationState** | Integer | Verification status of the email address
Possible values:
`0` = Unknown
`1` = Verified via double opt-in
`2` = Not verified |
| **meta.firstLogin** | String | Time of the first login (ISO 8601 format, UTC) |
| **meta.lastChangedAt** | String | Time of the last change to the account |
| **meta.lastChangedBy** | String | Source of the last change (e.g. "shop", "admin") |
| **meta.lastInvitedBy** | Integer | ID of the administrator who most recently sent an invitation link or password reset link to the user. |
| **meta.lastLogin** | String | Time of the last login (ISO 8601 format, UTC) |
| **meta.lastTimeAskedForPasswordReset** | String | Time when a password reset link was last requested (ISO 8601 format, UTC) |
| **meta.lastTimeInvitationLinkClicked** | String | Time when the invitation link was last clicked (ISO 8601 format, UTC) |
| **meta.lastTimeInvitationLinkSent** | String | Time when the invitation link was last sent (ISO 8601 format, UTC) |
| **moneySpent** | Float | Amount the account has spent so far, counted against the `paymentLimit` budget limit |
| **passwordResetRequired** | Boolean | Indicates whether the customer must change their password at the next login |
| **paymentLimit** | Integer | Global budget limit of the account across all orders (`0` = no limit) |
| **paymentLimitPerOrder** | Integer | Maximum order value per order (`0` = no limit) |
| **phone** | String | Phone number of the customer |
| **meta.invitationStatus** | String | Status of the account invitation. Possible values: `notSent`, `sent`, `expired`, `clicked` |
| **meta.invitationLinkValidUntil** | String | Validity of the invitation link (ISO 8601 timestamp, empty if not set) |
| **meta.passwordLinkValidUntil** | String | Validity of the password reset link (ISO 8601 timestamp, empty if not set) |
#### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"addresses": [
{
"additionalInfo": "",
"addressType": "1",
"businessFax": "",
"businessPhone": "",
"city": "asdf",
"company": "WEBSALE AG",
...
}
],
"allSubshopsAllowed": false,
"allowedSubshopIds": [
"deutsch"
],
"bankData": [
{
"accountNumber": "",
"bankCode": "",
"bankName": "myBank",
"bic": "INGDDEFFXXX",
"custom": null,
"iban": "DE746374637463746300",
...
}
],
"createdAt": "2024-09-03T10:09:34.000Z",
"customerNumber": "",
"deleted": false,
"displayName": "",
"email": "root@root.root",
"id": 1,
"loginBlocked": false,
"mainSubshop": "",
"meta": {
"currentLogin": "2025.04.16-12:12:04.899",
"dataSets": {
"accountBasketId": "",
"lastUsedBillAddressId": 108,
"lastUsedDeliveryAddressId": 108,
"lastUsedPaymentMethodId": "safepayment",
"lastUsedPseudoCCId": "",
"lastUsedShippingMethodId": "hermes",
"mainAddressId": 108
},
"emailVerificationState": 0,
"invitationLinkValidUntil": "",
"invitationStatus": "notSent",
"lastChangedAt": "1970.01.01-00:00:00.000",
"lastChangedBy": "shop",
"lastLogin": "2025.04.16-08:12:31.895",
"passwordLinkValidUntil": ""
},
"passwordResetRequired": false,
"phone": ""
}
```
### Data fields of an address
| **Name** | **Type** | **Meaning** |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **additionalInfo** | String | Additional address information (e.g. floor, house name, etc.) |
| **addressType** | String | Unknown (`"0"`), billing and delivery address (`"1"`), billing address (`"2"`), delivery address (`"3"`) |
| **businessFax** | String | Business fax |
| **businessPhone** | String | Business phone |
| **city** | String | City |
| **company** | String | Company name (if available) |
| **country** | String | Country code (input as ISO 3166-1 alpha-2/alpha-3/numeric, e.g. "DE"). In GET responses, the field is returned as an object with the fields: `isoAlpha2`, `isoAlpha3`, `isoNum`, `name` |
| **custom** | Object | User-defined fields |
| **dateOfBirth** | String | Date of birth |
| **department** | String | Department |
| **fax** | String | Fax number |
| **firstName** | String | First name |
| **id** | Integer | Unique ID of the address |
| **lastName** | String | Last name |
| **mobilePhone** | String | Mobile number |
| **phone** | String | Phone number |
| **salutationCode** | String | Salutation code (e.g. "1" for "Herr", "2" for "Frau") |
| **state** | String | State / region |
| **street** | String | Street name |
| **streetNumber** | String | House number |
| **taxId** | String | VAT ID |
| **titleCode** | String | Title code (e.g. "2" for "Dr.") |
| **zip** | String | Postal code |
| **externalId** | String | External ID for the address (optional) |
| **labels** | String\[] | List of labels/tags for the address (optional) |
| **updatedAt** | String | Timestamp of the last change (ISO 8601, only included in list responses) |
#### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"additionalInfo": "",
"addressType": "1",
"businessFax": "",
"businessPhone": "",
"city": "asdf",
"company": "WEBSALE AG",
"country": "DE",
"custom": null,
"dateOfBirth": "14.07.1967",
"department": "",
"externalId": "",
"fax": "",
"firstName": "asdff",
"id": 5,
"labels": [],
"lastName": "asdf",
"mobilePhone": "",
"phone": "+49123456789",
"salutationCode": "1",
"state": "",
"street": "asdf",
"streetNumber": "9",
"taxId": "",
"titleCode": "2",
"zip": "99999"
}
```
### Data fields of a bank account
| **Name** | **Type** | **Meaning** |
| -------------------------- | --------- | ------------------------------------------------------------------------ |
| **accountNumber** | String | ID of the payment account (legacy, mostly replaced by IBAN) |
| **bankCode** | String | Bank code (BLZ) of the credit institution |
| **bankName** | String | Name of the bank |
| **bic** | String | BIC (Business Identifier Code) of the bank for international payments |
| **custom** | Object | User-defined fields |
| **iban** | String | IBAN (International Bank Account Number) of the payment account |
| **id** | Integer | Unique ID of the bank data record |
| **owner** | String | Name of the account holder |
| **sepaDebitType** | String | Type of the SEPA direct debit scheme (e.g. "CORE", "B2B") |
| **sepaDirectDebitMandate** | String | Mandate reference number for SEPA direct debit |
| **sepaMandateDate** | String | Date the mandate was granted (e.g. 2025-01-01) |
| **sepaMandateType** | String | Type of the SEPA mandate (e.g. "first mandate", "follow-up mandate") |
| **externalId** | String | External ID for the bank account (optional) |
| **labels** | String\[] | List of labels/tags for the bank account (optional) |
| **updatedAt** | String | Timestamp of the last change (ISO 8601, only included in list responses) |
#### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"accountNumber": "",
"bankCode": "",
"bankName": "myBank",
"bic": "INGDDEFFXXX",
"custom": null,
"externalId": "",
"iban": "DE746374637463746300",
"id": 1778681,
"labels": [],
"owner": "Max Mustermann",
"sepaDebitType": "",
"sepaDirectDebitMandate": "",
"sepaMandateDate": "",
"sepaMandateType": ""
}
```
## Methods for customer data
The methods described here enable complete management of customer data in the system. This includes retrieving, creating, updating, and deleting customer accounts as well as exporting data and resetting passwords. In addition, information about already deleted accounts can be retrieved.
Different permissions apply to each operation to ensure that only authorized users can access the respective functions.
### GET customerAccounts
This method retrieves a paginated list of all customers in the shop system. In addition to basic customer information such as ID, email address, and phone number, each response also contains associated address and bank data.
Optional filter and sort parameters allow the results to be specifically restricted and sorted. The maximum number of results per request is 300.
Read permissions for customer data are required to access this interface.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"addresses": [
{
"city": "asdf",
"country": {
"isoAlpha2": "DE",
"isoAlpha3": "DEU",
"isoNum": "276",
"name": "Deutschland"
},
"firstName": "asdf",
"id": 108,
"lastName": "asdf",
"zip": "99999",
...
}
],
"allSubshopsAllowed": false,
"allowedSubshopIds": [
"deutsch",
"english"
],
"bankData": [
{
"accountNumber": "",
"bankCode": "",
"bankName": "foo",
"bic": "",
"iban": "",
"id": 7,
"owner": "bar",
...
}
],
"createdAt": "2024-09-03T10:09:34.000Z",
"customerNumber": "",
"deleted": false,
"email": "root@root.root",
"id": 1,
"loginBlocked": false,
"passwordResetRequired": false,
"phone": ""
},
...
],
"nextPageToken": "NDA",
"totalCount": 41
}
```
#### Filter fields
`id`, `customerNumber`, `loginBlocked`, `deleted`, `createdAt`, `updatedAt`
#### Sort fields
`id`, `customerNumber`, `loginBlockedAt`, `deletedAt`, `createdAt`, `updatedAt`
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------- | --------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read customer data. |
| 400 Bad Request | "invalidValue" | |
| 400 Bad Request | "invalidCharacters" | `size` is not an integer.
A filter value is invalid. |
| 400 Bad Request | "unknownDataField" | A filter or sort field is invalid. |
| 400 Bad Request | "unknownOperation" | A filter type is invalid. |
| 400 Bad Request | "syntaxError" | `sort` contains more than one or no ":". |
### GET customerAccounts/\{accountId}
This method loads the complete data of a customer account by its ID.
In addition to the master data such as email address, phone number, and customer number, the response also contains additional information such as allowed subshops, bank data, addresses, and metadata (e.g. last login or payment method used).
Read permissions for customer data are required to access this method. If no account with the specified ID is found, a corresponding error is returned.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"addresses": [
...
],
"allSubshopsAllowed": false,
"allowedSubshopIds": [
"deutsch",
"english"
],
"bankData": [
...
],
"createdAt": "2024-09-03T10:09:34.000Z",
"customerNumber": "",
"deleted": false,
"displayName": "",
"email": "root@root.root",
"id": 1,
"loginBlocked": false,
"mainSubshop": "",
"meta": {
"currentLogin": "2024.12.19-10:43:01.435",
"dataSets": {
"accountBasketId": "",
"lastUsedBillAddressId": 108,
"lastUsedDeliveryAddressId": 108,
"lastUsedPaymentMethodId": "prepayment",
"lastUsedPseudoCCId": "",
"lastUsedShippingMethodId": "dhl",
"mainAddressId": 108
},
"emailVerificationState": 0,
"invitationLinkValidUntil": "",
"invitationStatus": "notSent",
"lastChangedAt": "2024-09-03T10:09:34.000Z",
"lastChangedBy": "shop",
"lastLogin": "2024.12.18-20:56:30.823",
"passwordLinkValidUntil": ""
},
"passwordResetRequired": false,
"phone": ""
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | -------- | --------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read customer data. |
| 404 Not Found | | The account with `id`=`{accountId}` was not found. |
### GET customerDataDeleted
This method returns a list of customer data records that have been marked as deleted. Each entry contains the account ID, the time of deletion (`deletedAt`), and a type value describing the type of deleted data.
Filter and sort parameters are available to specifically restrict the result set. Read permissions for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerDataDeleted
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"deletedAt": "2024-10-02T11:22:41.000Z",
"id": 4,
"type": 0
},
...
],
"nextPageToken": "NDA",
"totalCount": 41
}
```
#### Filter fields
`id`, `type`, `deletedAt`
#### Sort fields
`id`, `type`, `deletedAt`
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------- | --------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read customer data. |
| 400 Bad Request | "invalidValue" | |
| 400 Bad Request | "invalidCharacters" | `size` is not an integer.
A filter value is invalid. |
| 400 Bad Request | "unknownDataField" | A filter or sort field is invalid. |
| 400 Bad Request | "unknownOperation" | A filter type is invalid. |
| 400 Bad Request | "syntaxError" | `sort` contains more than one or no ":". |
### POST customerAccounts
This method creates a new customer account. In addition to basic data such as email address, phone number, or password, settings for subshop assignment and preferred addresses can also be provided.
The request body must contain at least a valid email address and a password. Further optional fields such as `mainAddress` or `allowedSubshopIds` allow finer configuration of the account.
Optionally, an `accountId` (positive integer) can be provided to create the account with a specific ID. If no `accountId` is specified, the system automatically assigns a new ID.
Create rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"allSubshopsAllowed": false,
"allowedSubshopIds": [
"deutsch"
],
"createdAt": "2024-09-03T10:09:34.000Z",
"customerNumber": "",
"deleted": false,
"displayName": "",
"email": "root@root.root",
"id": 1,
"loginBlocked": false,
"mainSubshop": "",
"meta": {
"currentLogin": "",
"dataSets": {
"accountBasketId": "",
"lastUsedBillAddressId": 0,
"lastUsedDeliveryAddressId": 0,
"lastUsedPaymentMethodId": "",
"lastUsedPseudoCCId": "",
"lastUsedShippingMethodId": "",
"mainAddressId": 0
},
"emailVerificationState": 0,
"invitationLinkValidUntil": "",
"invitationStatus": "notSent",
"lastChangedAt": "2024-09-03T10:09:34.000Z",
"lastChangedBy": "adminInterface",
"lastLogin": "",
"passwordLinkValidUntil": ""
},
"passwordResetRequired": false,
"phone": ""
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to create customer data. |
| 400 Bad Request | | Request body could not be loaded, or creation failed. |
| 400 Bad Request | "unknownDataField" | An attempt was made to update something other than `accountId`, `customerNumber`, `email`, `phone`, `mainAddress`, `lastUsedBillAddressId`, `lastUsedDeliveryAddressId`, `password`, `passwordResetRequired`, `allSubshopsAllowed`, `allowedSubshopIds`, `displayName`, `mainSubshop`, `paymentLimit`, `paymentLimitPerOrder`, `enabledPaymentMethods`, or `blockedPaymentMethods`. |
| 400 Bad Request | "invalidValue" | A subshop ID is invalid. |
| 400 Bad Request | "invalidFormat" | `allowedSubshopIds`, `enabledPaymentMethods`, or `blockedPaymentMethods` is not an array of strings.
`allSubshopsAllowed` is not a boolean.
`customerNumber`, `phone`, `email`, `password` are not strings.
`mainAddress`, `lastUsedDeliveryAddressId`, or `lastUsedBillAddressId` are not numbers.
The email address has an invalid format. |
| 400 Bad Request | "missing" | `email` or `password` was not provided. |
| 409 Conflict | | Email or phone number is used by another account. |
### POST customerAccounts/\{accountId}/passwordReset
This method sends a password reset link to the email address stored in the customer account. This is helpful if a user has lost access to their account or wants to reset their password.
Write rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/passwordReset
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"passwordLinkValidUntil": "2025-09-12T12:51:59.000Z",
"success": true
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ----------------------- | -------------- | ------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to write customer data. |
| 400 Bad Request | "invalidValue" | `accountId` is not a positive integer.
The email address is invalid. |
| 404 Not Found | | The account with `id`=`{accountId}` was not found. |
| 400 Bad Request | "missing" | The account has no email address stored. |
| 409 Conflict | | A password reset link has already been sent within the last 24 hours. |
| 503 Service Unavailable | | Internal error when sending the password reset link. |
### PUT customerAccounts/\{accountId}
This method updates an existing customer account by its ID. Among other things, the email address, phone number, address references, and subshop assignment can be changed.
Write rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"email": "m.mustermann@email.com",
"passwordResetRequired": true,
"allowedSubshopIds": [
"deutsch",
"english"
]
}
```
### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"allSubshopsAllowed": false,
"allowedSubshopIds": [
"deutsch"
],
"createdAt": "2024-09-03T10:09:34.000Z",
"customerNumber": "",
"deleted": false,
"displayName": "",
"email": "root@root.root",
"id": 1,
"loginBlocked": false,
"mainSubshop": "",
"meta": {
"currentLogin": "2024.12.19-10:43:01.435",
"dataSets": {
"accountBasketId": "",
"lastUsedBillAddressId": 108,
"lastUsedDeliveryAddressId": 108,
"lastUsedPaymentMethodId": "prepayment",
"lastUsedPseudoCCId": "",
"lastUsedShippingMethodId": "dhl",
"mainAddressId": 108
},
"emailVerificationState": 0,
"invitationLinkValidUntil": "",
"invitationStatus": "notSent",
"lastChangedAt": "2024-09-03T11:00:00.000Z",
"lastChangedBy": "adminInterface",
"lastLogin": "2024.12.18-20:56:30.823",
"passwordLinkValidUntil": ""
},
"passwordResetRequired": false,
"phone": ""
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to write customer data. |
| 404 Not Found | | The account with `id`=`{accountId}` was not found. |
| 400 Bad Request | | Request body could not be loaded. |
| 400 Bad Request | "unknownDataField" | An attempt was made to update something other than `customerNumber`, `email`, `phone`, `mainAddress`, `lastUsedBillAddressId`, `lastUsedDeliveryAddressId`, `passwordResetRequired`, `allSubshopsAllowed`, `allowedSubshopIds`, `displayName`, `mainSubshop`, `paymentLimit`, `paymentLimitPerOrder`, `enabledPaymentMethods`, or `blockedPaymentMethods`. |
| 400 Bad Request | "invalidValue" | A subshop ID is invalid. |
| 400 Bad Request | "invalidFormat" | `allowedSubshopIds`, `enabledPaymentMethods`, or `blockedPaymentMethods` is not an array of strings.
`allSubshopsAllowed` is not a boolean.
`customerNumber`, `phone`, or `email` are not strings.
`mainAddress`, `lastUsedDeliveryAddressId`, or `lastUsedBillAddressId` are not numbers.
The email address has an invalid format. |
| 409 Conflict | | Email or phone number is used by another account. The response contains a `fieldName` field indicating which field caused the conflict (e.g. `"email"` or `"phone"`). |
### DELETE customerAccounts/\{accountId}
This method deletes a customer account by its ID. The deletion is permanent and removes the account, including all associated data, from the system.
Delete rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | -------- | ----------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to delete customer data. |
| 404 Not Found | | The account was not found. |
### GET customerAccounts/deleted
Returns a paginated list of deleted customer accounts. This method complements `GET customerDataDeleted` (section 3.3), which returns deleted address and bank data. Read rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/deleted
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"id": 42,
"deletedAt": "2025-06-15T10:30:00.000Z"
}
],
"nextPageToken": "",
"totalCount": 1
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | --------------- | --------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read customer data. |
| 400 Bad Request | "invalidParams" | Invalid search or filter parameters. |
### POST customerAccounts/\{accountId}/activate
Activates a customer account and sends an invitation email to the stored email address. The account must have a verified email address (or email verification must be disabled in the configuration). Invitation links can be sent at most once per 24 hours. Write rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/activate
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"invitationLinkValidUntil": "2025-09-12T12:51:59.000Z",
"success": true
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to write customer data. |
| 400 Bad Request | "invalidValue" | `accountId` is not a valid positive integer.
The `stage` is invalid (only "active" or "work" allowed).
The email address is invalid. |
| 400 Bad Request | "missing" | The account has no email address stored (`email` is missing). |
| 400 Bad Request | | The account's email address is not verified and email verification is enabled in the configuration. |
| 404 Not Found | | The account was not found. |
| 409 Conflict | | An invitation has already been sent within the last 24 hours. |
| 503 Service Unavailable | | Internal error when sending the invitation email. |
### GET customerAccounts/\{accountId}/link
Generates a temporary login link via which a customer can log in directly to the shop. The link is valid for 30 seconds. Write and delete rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/link
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"link": "https://www..de?sessionKey=abc123...",
"success": true
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ----------------------- | -------------- | ----------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required write and delete rights for customer data. |
| 404 Not Found | | The account was not found. |
| 503 Service Unavailable | Internal error | Redis service is not available.
Sending the email failed. |
## Methods for addresses and bank data
This section describes the methods for managing addresses and bank data within a customer account.
Both data types are handled structurally the same: storage and loading are done in the same way. The only difference lies in the endpoint — instead of `addresses`, `bankData` is used in the URL for bank data.
### GET customerAccounts/\{accountId}/addresses
This method retrieves all available addresses of a specific customer account. The request returns a list of all address data records linked to the specified account.
The endpoint described here applies analogously to bank data — simply replace `addresses` with `bankData` in the path.
A corresponding read permission is required for access.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/addresses
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
{
"additionalInfo": "",
"addressType": "1",
"businessFax": "",
"businessPhone": "",
"city": "asdf",
"company": "WEBSALE AG",
"country": {
"isoAlpha2": "DE",
"isoAlpha3": "DEU",
"isoNum": "276",
"name": "Deutschland"
},
"custom": null,
"dateOfBirth": "14.07.1967",
"department": "",
"externalId": "",
"fax": "",
"firstName": "asdff",
"id": 5,
"labels": [],
"lastName": "asdf",
"mobilePhone": "",
"phone": "+49123456789",
"salutationCode": "1",
"state": "",
"street": "asdf",
"streetNumber": "9",
"taxId": "",
"titleCode": "2",
"zip": "99999"
},
{
"additionalInfo": "",
"addressType": "",
"businessFax": "",
"businessPhone": "",
"city": "",
"company": "",
"country": "",
"custom": null,
"dateOfBirth": "",
"department": "",
"externalId": "",
"fax": "",
"firstName": "",
"id": 141,
"labels": [],
"lastName": "",
"mobilePhone": "",
"phone": "",
"salutationCode": "",
"state": "",
"street": "",
"streetNumber": "",
"taxId": "",
"titleCode": "",
"zip": ""
}
]
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | -------- | --------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read customer data. |
| 404 Not Found | | The account with `id`=`{accountId}` was not found. |
### GET customerAccounts/\{accountId}/addresses/\{id}
This method returns the details of a single address assigned to a specific customer account. The address is retrieved by its ID.
The endpoint described here applies analogously to bank data — simply replace `addresses` with `bankData` in the path.
Access requires a valid read permission for customer data.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/addresses/5
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"additionalInfo": "",
"addressType": "1",
"businessFax": "",
"businessPhone": "",
"city": "asdf",
"company": "WEBSALE AG",
"country": {
"isoAlpha2": "DE",
"isoAlpha3": "DEU",
"isoNum": "276",
"name": "Deutschland"
},
"custom": null,
"dateOfBirth": "",
"department": "",
"externalId": "",
"fax": "",
"firstName": "asdff",
"id": 5,
"labels": [],
"lastName": "asdf",
"mobilePhone": "",
"phone": "+49123456789",
"salutationCode": "1",
"state": "",
"street": "asdf",
"streetNumber": "9",
"taxId": "",
"titleCode": "2",
"zip": "99999"
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | -------- | ------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read customer data. |
| 404 Not Found | | The account with `id`=`{accountId}` was not found.
The address was not found. |
### POST customerAccounts/\{accountId}/addresses
This method creates a new address for a specific customer account. The required fields for the address are provided in the request body. Validation is performed server-side, and erroneous fields are specifically named in the server response.
The endpoint described here applies analogously to bank data — simply replace `addresses` with `bankData` in the path.
Write and create rights for customer data are required for execution.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/addresses
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"custom": {},
"addressType": "1",
"salutationCode": "1",
"lastName": "Mustermann",
"firstName": "Max",
"street": "Musterstraße",
"streetNumber": "54",
"zip": "12345",
"city": "Musterstadt",
"country": "DE",
"dateOfBirth": "14.07.1967",
"phone": "+49123456789"
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"additionalInfo": "",
"addressType": "1",
"businessFax": "",
"businessPhone": "",
"city": "Musterstadt",
"company": "",
"country": {
"isoAlpha2": "DE",
"isoAlpha3": "DEU",
"isoNum": "276",
"name": "Deutschland"
},
"custom": null,
"dateOfBirth": "14.07.1967",
"department": "",
"externalId": "",
"fax": "",
"firstName": "Max",
"id": 158,
"labels": [],
"lastName": "Mustermann",
"mobilePhone": "",
"phone": "+49123456789",
"salutationCode": "1",
"state": "",
"street": "Musterstrasse",
"streetNumber": "54",
"taxId": "",
"titleCode": "",
"zip": "12345"
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required write and create rights for customer data. |
| 400 Bad Request | | Request body could not be loaded.
Updating failed. |
| 400 Bad Request | "unknownDataField" | An unknown field is being updated. |
| 400 Bad Request | "invalidFormat" | `custom` is not an object.
`externalId` is not a string.
`labels` is not an array or contains non-string values. |
| 404 Not found | | The address was not found. |
### PUT customerAccounts/\{accountId}/addresses/\{id}
This method updates an existing address of a customer account. Only the fields provided are changed; a complete address structure is not required. Validation is performed server-side — erroneous fields are indicated in the response.
The endpoint described here applies analogously to bank data — simply replace `addresses` with `bankData` in the path.
Permission to write customer data is required for execution.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/addresses/5
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"custom": {},
"zip": "99999",
"firstName": "foo"
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"additionalInfo": "",
"addressType": "1",
"businessFax": "",
"businessPhone": "",
"city": "Musterstadt",
"company": "",
"country": {
"isoAlpha2": "DE",
"isoAlpha3": "DEU",
"isoNum": "276",
"name": "Deutschland"
},
"custom": null,
"dateOfBirth": "14.07.1967",
"department": "",
"externalId": "",
"fax": "",
"firstName": "foo",
"id": 5,
"labels": [],
"lastName": "Mustermann",
"mobilePhone": "",
"phone": "+49123456789",
"salutationCode": "1",
"state": "",
"street": "Musterstrasse",
"streetNumber": "54",
"taxId": "",
"titleCode": "2",
"zip": "99999"
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to write customer data. |
| 400 Bad Request | | Request body could not be loaded.
Updating failed. |
| 400 Bad Request | "unknownDataField" | An unknown field is being updated. |
| 400 Bad Request | "invalidFormat" | `custom` is not an object.
`externalId` is not a string.
`labels` is not an array or contains non-string values. |
| 404 Not found | | The address was not found. |
### DELETE customerAccounts/\{accountId}/addresses/\{id}
This method deletes an address from a customer account. It is checked whether the address actually belongs to the specified account.
The endpoint described here applies analogously to bank data — simply replace `addresses` with `bankData` in the path.
Write and delete rights for customer data are required for execution.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/customerAccounts/1/addresses/5
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | -------- | ------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required write and delete rights for customer data. |
| 404 Not Found | | The account with `id`=`{accountId}` was not found.
The address was not found. |
| 409 Conflict | | `{accountId}` and the ID of the account to which the address belongs do not match. |
## Bulk methods
This section describes the bulk endpoints that can be used to query or process multiple data records in a single request.
### GET bulk/lastOrderTimestamp
Returns the timestamp of the last order for multiple customer accounts. Invalid account IDs and accounts without orders are skipped. Read rights for customer data are required.
The mandatory `accountId` (Integer) parameter specifies the customer account ID and can be specified multiple times to query multiple accounts.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/bulk/lastOrderTimestamp?accountId=1&accountId=2&accountId=3
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
{
"accountId": 1,
"lastOrderTimestamp": "2025-01-15T10:30:00Z"
},
{
"accountId": 3,
"lastOrderTimestamp": "2025-03-20T14:22:00Z"
}
]
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | -------- | --------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required permissions to read customer data. |
### POST bulk/customerAccounts
Enables bulk creation and updating of customer accounts in a single request. The request body is a JSON array in which each element describes an action (create or update). Create and write rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/bulk/customerAccounts
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"type": "create",
"data": {
"email": "neu@example.com",
"firstName": "Max",
"lastName": "Mustermann"
}
},
{
"type": "update",
"accountId": 42,
"data": {
"firstName": "Maria"
}
}
]
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [101, 42],
"skippedLines": [
{
"lineNumber": 3,
"errorType": "invalidParameters",
"fieldErrors": {
"email": {
"type": "missing"
}
}
}
]
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required create and write rights for customer data. |
| 400 Bad Request | "invalidFormat" | The request body is not a JSON array, or the maximum number of entries was exceeded. |
| skippedLines | "invalidParameters" | Mandatory fields are missing (e.g. `type`), field type does not match, invalid value for `type` (not `"create"` or `"update"`), or `accountId` is missing for `"update"`. |
| skippedLines | "invalidFields" | Invalid fields when updating a customer account. |
| skippedLines | "conflict" | Email address or customer number already assigned. |
| skippedLines | "notFound" | Customer account with the specified `accountId` was not found. |
| skippedLines | "internalError" | Internal error when creating the customer account. |
### POST bulk/customerAccounts/addresses
Enables bulk creation and updating of customer addresses in a single request. The request body is a JSON array in which each element describes an action (create or update) for an address. Create and write rights for customer data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/bulk/customerAccounts/addresses
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"type": "create",
"accountId": 42,
"data": {
"firstName": "Max",
"lastName": "Mustermann",
"street": "Musterstraße 1",
"zip": "12345",
"city": "Musterstadt"
}
},
{
"type": "update",
"accountId": 42,
"addressId": 7,
"data": {
"city": "Berlin"
}
}
]
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [15, 7],
"skippedLines": [
{
"lineNumber": 3,
"errorType": "notFound",
"fieldErrors": {}
}
]
}
```
#### Error codes
| **Error** | **Type** | **Reason** |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Not authorized: you are not logged in. |
| 403 Forbidden | | You do not have the required create and write rights for customer data. |
| 400 Bad Request | "invalidFormat" | The request body is not a JSON array, or the maximum number of entries was exceeded. |
| skippedLines | "invalidParameters" | Mandatory fields are missing (e.g. `type`, `accountId`), field type does not match, invalid value for `type` (not `"create"` or `"update"`), `addressId` is missing for `"update"`, or invalid address data. |
| skippedLines | "notFound" | Customer account with the specified `accountId` or address with the specified `addressId` was not found. |
## Support
Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)
Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.