API reference customer data - WEBSALE Dokumentation

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
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
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)
passwordResetRequired	Boolean	Indicates whether the customer must change their password at the next login
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

{
    "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

{
    "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

{
    "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

https://www.<your-shop>.de/admin/api/v1/customerAccounts

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerDataDeleted

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts

Response

{
    "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 or 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`, or `mainSubshop`.
400 Bad Request	”invalidValue”	A subshop ID is invalid.
400 Bad Request	”invalidFormat”	`allowedSubshopIds` 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/passwordReset

Response

{
    "passwordLinkValidUntil": "2025-09-12T12:51:59.000Z",
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1

Request body

{
    "email": "m.mustermann@email.com",
    "passwordResetRequired": true,
    "allowedSubshopIds": [
        "deutsch",
        "english"
    ]
}

Response

{
    "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 or 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`, or `mainSubshop`.
400 Bad Request	”invalidValue”	A subshop ID is invalid.
400 Bad Request	”invalidFormat”	`allowedSubshopIds` 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/deleted

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/activate

Response

{
    "invitationLinkValidUntil": "2025-09-12T12:51:59.000Z",
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/link

Response

{
    "link": "https://www.<your-shop>.de?sessionKey=abc123...",
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/addresses

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/addresses/5

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/addresses

Request body

{
    "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

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/addresses/5

Request body

{
    "custom": {},
    "zip": "99999",
    "firstName": "foo"
}

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/customerAccounts/1/addresses/5

Response

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or 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

https://www.<your-shop>.de/admin/api/v1/bulk/lastOrderTimestamp?accountId=1&accountId=2&accountId=3

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/bulk/customerAccounts

Request body

[
    {
        "type": "create",
        "data": {
            "email": "neu@example.com",
            "firstName": "Max",
            "lastName": "Mustermann"
        }
    },
    {
        "type": "update",
        "accountId": 42,
        "data": {
            "firstName": "Maria"
        }
    }
]

Response

{
    "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 or 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

https://www.<your-shop>.de/admin/api/v1/bulk/customerAccounts/addresses

Request body

[
    {
        "type": "create",
        "accountId": 42,
        "data": {
            "firstName": "Max",
            "lastName": "Mustermann",
            "street": "Musterstra&szlig;e 1",
            "zip": "12345",
            "city": "Musterstadt"
        }
    },
    {
        "type": "update",
        "accountId": 42,
        "addressId": 7,
        "data": {
            "city": "Berlin"
        }
    }
]

Response

{
    "items": [15, 7],
    "skippedLines": [
        {
            "lineNumber": 3,
            "errorType": "notFound",
            "fieldErrors": {}
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in or 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 Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields

​Data fields of a customer account

​Example

​Data fields of an address

​Example

​Data fields of a bank account

​Example

​Methods for customer data

​GET customerAccounts

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET customerAccounts/{accountId}

​Example

​Response

​Error codes

​GET customerDataDeleted

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​POST customerAccounts

​Example

​Response

​Error codes

​POST customerAccounts/{accountId}/passwordReset

​Example

​Response

​Error codes

​PUT customerAccounts/{accountId}

​Example

​Request body

​Response

​Error codes

​DELETE customerAccounts/{accountId}

​Example

​Response

​Error codes

​GET customerAccounts/deleted

​Example

​Response

​Error codes

​POST customerAccounts/{accountId}/activate

​Example

​Response

​Error codes

​GET customerAccounts/{accountId}/link

​Example

​Response

​Error codes

​Methods for addresses and bank data

​GET customerAccounts/{accountId}/addresses

​Example

​Response

​Error codes

​GET customerAccounts/{accountId}/addresses/{id}

​Example

​Response

​Error codes

​POST customerAccounts/{accountId}/addresses

​Example

​Request body

​Response

​Error codes

​PUT customerAccounts/{accountId}/addresses/{id}

​Example

​Request body

​Response

​Error codes

​DELETE customerAccounts/{accountId}/addresses/{id}

​Example

​Response

​Error codes

​Bulk methods

​GET bulk/lastOrderTimestamp

​Example

Supported methods

Data fields

Data fields of a customer account

Example

Data fields of an address

Example

Data fields of a bank account

Example

Methods for customer data

GET customerAccounts

Example

Response

Filter fields

Sort fields

Error codes

GET customerAccounts/{accountId}

Example

Response

Error codes

GET customerDataDeleted

Example

Response

Filter fields

Sort fields

Error codes

POST customerAccounts

Example

Response

Error codes

POST customerAccounts/{accountId}/passwordReset

Example

Response

Error codes

PUT customerAccounts/{accountId}

Example

Request body

Response

Error codes

DELETE customerAccounts/{accountId}

Example

Response

Error codes

GET customerAccounts/deleted

Example

Response

Error codes

POST customerAccounts/{accountId}/activate

Example

Response

Error codes

GET customerAccounts/{accountId}/link

Example

Response

Error codes

Methods for addresses and bank data

GET customerAccounts/{accountId}/addresses

Example

Response

Error codes

GET customerAccounts/{accountId}/addresses/{id}

Example

Response

Error codes

POST customerAccounts/{accountId}/addresses

Example

Request body

Response

Error codes

PUT customerAccounts/{accountId}/addresses/{id}

Example

Request body

Response

Error codes

DELETE customerAccounts/{accountId}/addresses/{id}

Example

Response

Error codes

Bulk methods

GET bulk/lastOrderTimestamp

Example