API-Referenz Kundendaten - WEBSALE Dokumentation

Der Endpunkt customerAccounts/ stellt eine REST-Schnittstelle zur Verfügung, über die Kundendaten im Shop-System verwaltet werden können. Die API ermöglicht das Erstellen, Abrufen, Aktualisieren und Löschen von Kundenkonten, Adressen und Bankverbindungen. Zusätzlich lassen sich Daten exportieren oder Passwortrücksetzungen initiieren. Alle Endpunkte sind so gestaltet, dass sie eine systematische Verwaltung und Pflege von Kundendaten über das Admin-Interface hinaus ermöglichen.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Kundendaten	customerAccounts/
Adressen	customerAccounts/…/addresses
Bankdaten	customerAccounts/…/bankData
Bulk-Abfragen	bulk/

Datenfelder

Datenfelder eines Kundenkontos

Name	Typ	Bedeutung
allSubshopsAllowed	Boolean	Gibt an, ob der Kunde für alle Subshops freigeschaltet ist
allowedSubshopIds	String[]	Liste der Subshops, für die der Kunde freigeschaltet ist
createdAt	String	Zeitpunkt der Kontoerstellung (ISO 8601-Format, UTC)
customerNumber	String	Vom System oder extern vergebene Kundennummer
deleted	Boolean	Gibt an, ob das Konto gelöscht wurde
displayName	String	Anzeigename des Kunden (wird z. B. bei Kommentaren oder Bewertungen angezeigt)
email	String	E-Mail-Adresse des Kunden
id	Integer	Interne eindeutige ID des Kunden
loginBlocked	Boolean	Gibt an, ob der Login für dieses Konto gesperrt ist
mainSubshop	String	Haupt-Subshop
meta.currentLogin	String	Zeitpunkt des aktuellen Logins (ISO 8601-Format, UTC)
meta.dataSets.accountBasketId	String	Das zugeordnete Warenkorb-ID des Kundenkontos
meta.dataSets.lastUsedBillAddressId	Integer	ID der zuletzt genutzten Rechnungsadresse
meta.dataSets.lastUsedDeliveryAddressId	Integer	ID der zuletzt genutzten Lieferadresse
meta.dataSets.lastUsedPaymentMethodId	String	ID der zuletzt verwendeten Zahlungsart
meta.dataSets.lastUsedPseudoCCId	String	ID, anhand der Kreditkartendaten zum letzten Mal gefunden wurden
meta.dataSets.lastUsedShippingMethodId	String	ID der zuletzt genutzten Versandart
meta.dataSets.mainAddressId	Integer	ID der Hauptadresse des Kunden
meta.emailVerificationState	Integer	Verifizierungsstatus der E-Mail-Adresse Mögliche Werte: `0` = Unbekannt `1` = Verifiziert durch Double-Opt-In `2` = Nicht verifiziert
meta.firstLogin	String	Zeitpunkt des ersten Logins (ISO 8601-Format, UTC)
meta.lastChangedAt	String	Zeitpunkt der letzten Änderung am Konto
meta.lastChangedBy	String	Quelle der letzten Änderung (z. B. „shop“, “admin”)
meta.lastInvitedBy	Integer	ID des Administrators, der zuletzt einen Einladungslink oder einen Passwort-Reset-Link an den Benutzer gesendet hat.
meta.lastLogin	String	Zeitpunkt des letzten Logins (ISO 8601-Format, UTC)
meta.lastTimeAskedForPasswordReset	String	Zeitpunkt, zu dem zuletzt ein Passwort-Reset-Link angefordert wurde (ISO 8601-Format, UTC)
meta.lastTimeInvitationLinkClicked	String	Zeutpunkt, zu dem der Einladungslink zuletzt angeklickt wurde (ISO 8601-Format, UTC)
meta.lastTimeInvitationLinkSent	String	Zeitpunkt, zu dem der Einladungslink zuletzt versendet wurde (ISO 8601-Format, UTC)
passwordResetRequired	Boolean	Gibt an, ob der Kunde beim nächsten Login sein Passwort ändern muss
phone	String	Telefonnummer des Kunden
meta.invitationStatus	String	Status der Konto-Einladung. Mögliche Werte: `notSent`, `sent`, `expired`, `clicked`
meta.invitationLinkValidUntil	String	Gültigkeit des Einladungslinks (ISO 8601 Zeitstempel, leer wenn nicht gesetzt)
meta.passwordLinkValidUntil	String	Gültigkeit des Passwort-Reset-Links (ISO 8601 Zeitstempel, leer wenn nicht gesetzt)

Beispiel

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

Datenfelder einer Adresse

Name	Typ	Bedeutung
additionalInfo	String	Zusätzliche Adressinformationen (z. B. Etage, Hausname etc.)
addressType	String	Unbekannt (`"0"`), Rechnungs- und Lieferadresse (`"1"`), Rechnungsadresse (`"2"`), Lieferadresse (`"3"`)
businessFax	String	Geschäftsfax
businessPhone	String	Geschäftstelefon
city	String	Stadt
company	String	Firmenname (sofern vorhanden)
country	String	Ländercode (Eingabe als ISO 3166-1 alpha-2/alpha-3/numerisch, z. B. “DE”). In GET-Responses wird das Feld als Objekt zurückgegeben mit den Feldern: `isoAlpha2`, `isoAlpha3`, `isoNum`, `name`
custom	Objekt	Benutzerdefinierte Felder
dateOfBirth	String	Geburtsdatum
department	String	Abteilung
fax	String	Faxnummer
firstName	String	Vorname
id	Integer	Eindeutige ID der Adresse
lastName	String	Nachname
mobilePhone	String	Mobilnummer
phone	String	Telefonnummer
salutationCode	String	Anrede-Code (z. B. “1” für “Herr”, “2” für “Frau”)
state	String	Bundesland / Region
street	String	Straßenname
streetNumber	String	Hausnummer
taxId	String	Mehrwertsteuer-ID
titleCode	String	Titel-Code (z. B. “2” für “Dr.”)
zip	String	Postleitzahl
externalId	String	Externe ID für die Adresse (optional)
labels	String[]	Liste von Labels/Tags für die Adresse (optional)
updatedAt	String	Zeitstempel der letzten Änderung (ISO 8601, nur in Listen-Responses enthalten)

Beispiel

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

Datenfelder eines Bankkontos

Name	Typ	Bedeutung
accountNumber	String	ID des Zahlungskontos (veraltet, meist durch IBAN ersetzt)
bankCode	String	Bankleitzahl (BLZ) des Kreditinstituts
bankName	String	Name der Bank
bic	String	BIC (Business Identifier Code) der Bank für internationale Zahlungen
custom	Objekt	Benutzerdefinierte Felder
iban	String	IBAN (Internationale Bankkontonummer) des Zahlungskontos
id	Integer	Eindeutige ID des Bankdatensatzes
owner	String	Name des Kontoinhabers
sepaDebitType	String	Typ des SEPA-Lastschriftverfahrens (z. B. “CORE”, “B2B”)
sepaDirectDebitMandate	String	Mandatsreferenznummer für SEPA-Lastschrift
sepaMandateDate	String	Datum der Mandatserteilung (z. B. 2025-01-01)
sepaMandateType	String	Art des SEPA-Mandats (z. B. “Erstmandat”, “Folgemandat”)
externalId	String	Externe ID für die Bankverbindung (optional)
labels	String[]	Liste von Labels/Tags für die Bankverbindung (optional)
updatedAt	String	Zeitstempel der letzten Änderung (ISO 8601, nur in Listen-Responses enthalten)

Beispiel

{
    "accountNumber": "",
    "bankCode": "",
    "bankName": "myBank",
    "bic": "INGDDEFFXXX",
    "custom": null,
    "externalId": "",
    "iban": "DE746374637463746300",
    "id": 1778681,
    "labels": [],
    "owner": "Max Mustermann",
    "sepaDebitType": "",
    "sepaDirectDebitMandate": "",
    "sepaMandateDate": "",
    "sepaMandateType": ""
}

Methoden für Kundendaten

Die hier beschriebenen Methoden ermöglichen das vollständige Verwalten von Kundendaten im System. Dazu zählen das Abrufen, Erstellen, Aktualisieren und Löschen von Kundenkonten sowie das Exportieren von Daten und das Zurücksetzen von Passwörtern. Zusätzlich können Informationen über bereits gelöschte Konten abgerufen werden. Für jede Operation gelten unterschiedliche Berechtigungen, die sicherstellen, dass nur autorisierte Benutzer auf die jeweiligen Funktionen zugreifen können.

GET customerAccounts

Mit dieser Methode wird eine paginierte Liste aller Kunden im Shop-System abgerufen. Neben grundlegenden Kundeninformationen wie ID, E-Mail-Adresse und Telefonnummer enthält jede Antwort auch zugehörige Adress- und Bankdaten. Über optionale Filter- und Sortierparameter lassen sich die Ergebnisse gezielt einschränken und sortieren. Die maximale Anzahl an Ergebnissen pro Anfrage beträgt 300. Für den Zugriff auf diese Schnittstelle sind Leseberechtigungen für Kundendaten erforderlich.

Beispiel

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

Antwort

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

Filterfelder

id, customerNumber, loginBlocked, deleted, createdAt, updatedAt

Sortierfelder

id, customerNumber, loginBlockedAt, deletedAt, createdAt, updatedAt

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
400 Bad Request	”invalidValue”
400 Bad Request	”invalidCharacters”	`size` ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:”.

GET customerAccounts/

Diese Methode lädt die vollständigen Daten eines Kundenkontos anhand seiner ID. Die Antwort enthält neben den Stammdaten wie E-Mail-Adresse, Telefonnummer und Kundennummer auch Zusatzinformationen wie erlaubte Subshops, Bankdaten, Adressen und Metadaten (z. B. letzter Login oder verwendete Zahlungsart). Zum Zugriff auf diese Methode sind Leseberechtigungen für Kundendaten erforderlich. Wird kein Konto mit der angegebenen ID gefunden, wird ein entsprechender Fehler zurückgegeben.

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
404 Not Found		Das Konto mit `id`=`{accountId}` wurde nicht gefunden.

GET customerDataDeleted

Diese Methode liefert eine Liste von Kundendatensätzen, die als gelöscht markiert wurden. Jeder Eintrag enthält die ID des Kontos, den Zeitpunkt der Löschung (deletedAt) sowie einen Typenwert, der die Art der gelöschten Daten beschreibt. Filter- und Sortierparameter stehen zur Verfügung, um die Ergebnismenge gezielt einzuschränken. Leseberechtigungen für Kundendaten sind erforderlich.

Beispiel

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

Antwort

{
    "endReached": true,
    "items": [
        {
            "deletedAt": "2024-10-02T11:22:41.000Z",
            "id": 4,
            "type": 0
        },
        ...
    ],
    "nextPageToken": "NDA",
    "totalCount": 41
}

Filterfelder

id, type, deletedAt

Sortierfelder

id, type, deletedAt

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
400 Bad Request	”invalidValue”
400 Bad Request	”invalidCharacters”	`size` ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:”.

POST customerAccounts

Diese Methode erstellt ein neues Kundenkonto. Neben Basisdaten wie E-Mail-Adresse, Telefonnummer oder Passwort können auch Einstellungen zur Subshop-Zuweisung und bevorzugten Adressen übergeben werden. Der Request-Body muss mindestens eine gültige E-Mail-Adresse und ein Passwort enthalten. Weitere optionale Felder wie mainAddress oder allowedSubshopIds ermöglichen eine feinere Konfiguration des Kontos. Optional kann eine accountId (positive Ganzzahl) mitgegeben werden, um das Konto mit einer bestimmten ID anzulegen. Wird keine accountId angegeben, vergibt das System automatisch eine neue ID. Erstellrechte für Kundendaten sind erforderlich.

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Kundendaten.
400 Bad Request		Request body konnte nicht geladen werden, oder das Erstellen ist fehlgeschlagen.
400 Bad Request	”unknownDataField”	Man versucht, etwas außer `accountId`, `customerNumber`, `email`, `phone`, `mainAddress`, `lastUsedBillAddressId`, `lastUsedDeliveryAddressId`, `password`, `passwordResetRequired`, `allSubshopsAllowed`, `allowedSubshopIds`, `displayName` oder `mainSubshop` zu aktualisieren.
400 Bad Request	”invalidValue”	Eine Subshop-Id ist ungültig.
400 Bad Request	”invalidFormat”	`allowedSubshopIds` ist kein Array von Strings. `allSubshopsAllowed` ist kein Boolean. `customerNumber`, `phone`, `email`, `password` sind keine Strings. `mainAddress`, `lastUsedDeliveryAddressId` oder `lastUsedBillAddressId` sind keine Zahlen. Die E-Mail-Adresse hat ein ungültiges Format.
400 Bad Request	”missing”	`email` oder `password` wurden nicht übergeben.
409 Conflict		E-Mail oder Telefonnummer werden bei einem anderen Konto verwendet.

POST customerAccounts//passwordReset

Diese Methode versendet einen Link zum Zurücksetzen des Passworts an die im Kundenkonto hinterlegte E-Mail-Adresse. Das ist hilfreich, wenn ein Benutzer den Zugriff auf sein Konto verloren hat oder das Passwort zurücksetzen möchte. Schreibrechte für Kundendaten sind erforderlich.

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kundendaten.
400 Bad Request	”invalidValue”	`accountId` ist keine positive Ganzzahl. Die E-Mail-Adresse ist ungültig.
404 Not Found		Das Konto mit `id`=`{accountId}` wurde nicht gefunden.
400 Bad Request	”missing”	Das Konto hat keine E-Mail-Adresse hinterlegt.
409 Conflict		Ein Passwort-Reset-Link wurde innerhalb der letzten 24 Stunden bereits gesendet.
503 Service Unavailable		Interner Fehler beim Versenden des Passwort-Reset-Links.

PUT customerAccounts/

Mit dieser Methode wird ein bestehendes Kundenkonto anhand seiner ID aktualisiert. Es können unter anderem E-Mail-Adresse, Telefonnummer, Adressverweise und die Subshop-Zuordnung geändert werden. Schreibrechte für Kundendaten sind erforderlich.

Beispiel

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

Request Body

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kundendaten.
404 Not Found		Das Konto mit `id`=`{accountId}` wurde nicht gefunden.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”unknownDataField”	Man versucht, etwas außer `customerNumber`, `email`, `phone`, `mainAddress`, `lastUsedBillAddressId`, `lastUsedDeliveryAddressId`, `passwordResetRequired`, `allSubshopsAllowed`, `allowedSubshopIds`, `displayName` oder `mainSubshop` zu aktualisieren.
400 Bad Request	”invalidValue”	Eine Subshop-Id ist ungültig.
400 Bad Request	”invalidFormat”	`allowedSubshopIds` ist kein Array von Strings. `allSubshopsAllowed` ist kein Boolean. `customerNumber`, `phone` oder `email` sind keine Strings. `mainAddress`, `lastUsedDeliveryAddressId` oder `lastUsedBillAddressId` sind keine Zahlen. Die E-Mail-Adresse hat ein ungültiges Format.
409 Conflict		E-Mail oder Telefonnummer werden bei einem anderen Konto verwendet. Die Antwort enthält ein Feld `fieldName`, das angibt, welches Feld den Konflikt verursacht hat (z. B. `"email"` oder `"phone"`).

DELETE customerAccounts/

Mit dieser Methode wird ein Kundenkonto anhand seiner ID gelöscht. Die Löschung ist dauerhaft und entfernt das Konto einschließlich aller zugehörigen Daten aus dem System. Löschrechte für Kundendaten sind erforderlich.

Beispiel

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

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Kundendaten.
404 Not Found		Das Konto wurde nicht gefunden.

GET customerAccounts/deleted

Gibt eine paginierte Liste gelöschter Kundenkonten zurück. Diese Methode ergänzt GET customerDataDeleted (Abschnitt 3.3), die gelöschte Adress- und Bankdaten liefert. Leserechte für Kundendaten sind erforderlich.

Beispiel

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

Antwort

{
    "endReached": true,
    "items": [
        {
            "id": 42,
            "deletedAt": "2025-06-15T10:30:00.000Z"
        }
    ],
    "nextPageToken": "",
    "totalCount": 1
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
400 Bad Request	”invalidParams”	Ungültige Such- oder Filterparameter.

POST customerAccounts//activate

Aktiviert ein Kundenkonto und versendet eine Einladungs-E-Mail an die hinterlegte E-Mail-Adresse. Das Konto muss eine verifizierte E-Mail-Adresse besitzen (bzw. die E-Mail-Verifizierung muss in der Konfiguration deaktiviert sein). Einladungslinks können maximal einmal pro 24 Stunden versendet werden. Schreibrechte für Kundendaten sind erforderlich.

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kundendaten.
400 Bad Request	”invalidValue”	`accountId` ist keine gültige positive Ganzzahl. Die `stage` ist ungültig (nur “active” oder “work” erlaubt). Die E-Mail-Adresse ist ungültig.
400 Bad Request	”missing”	Das Konto hat keine E-Mail-Adresse hinterlegt (`email` fehlt).
400 Bad Request		Die E-Mail-Adresse des Kontos ist nicht verifiziert und die E-Mail-Verifizierung ist in der Konfiguration aktiviert.
404 Not Found		Das Konto wurde nicht gefunden.
409 Conflict		Es wurde innerhalb der letzten 24 Stunden bereits eine Einladung versendet.
503 Service Unavailable		Interner Fehler beim Versenden der Einladungs-E-Mail.

GET customerAccounts//link

Erzeugt einen temporären Login-Link, über den sich ein Kunde direkt im Shop einloggen kann. Der Link ist 30 Sekunden gültig. Schreib- und Löschrechte für Kundendaten sind erforderlich.

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Schreib- und Löschrechte für Kundendaten.
404 Not Found		Das Konto wurde nicht gefunden.
503 Service Unavailable	Internal error	Redis-Service ist nicht verfügbar. Das Senden der E-Mail ist fehlgeschlagen.

Methoden für Adressen und Bankdaten

In diesem Abschnitt werden die Methoden zur Verwaltung von Adressen und Bankdaten innerhalb eines Kundenkontos beschrieben. Beide Datentypen werden strukturell gleich behandelt: Die Speicherung und das Laden erfolgen auf dieselbe Weise. Der Unterschied liegt ausschließlich im Endpunkt – statt addresses wird für Bankdaten bankData in der URL verwendet.

GET customerAccounts//addresses

Mit dieser Methode können alle zur Verfügung stehenden Adressen eines bestimmten Kundenkontos abgerufen werden. Die Anfrage liefert eine Liste aller Adressdatensätze, die mit dem angegebenen Konto verknüpft sind. Der hier beschriebene Endpunkt gilt analog auch für Bankdaten – ersetzen Sie dafür im Pfad einfach addresses durch bankData. Für den Zugriff ist eine entsprechende Leseberechtigung erforderlich.

Beispiel

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

Antwort

{
    "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": ""
        }
    ]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
404 Not Found		Das Konto mit `id`=`{accountId}` wurde nicht gefunden.

GET customerAccounts//addresses/

Diese Methode liefert die Details einer einzelnen Adresse, die einem bestimmten Kundenkonto zugeordnet ist. Die Adresse wird anhand ihrer ID abgerufen. Der hier beschriebene Endpunkt gilt analog auch für Bankdaten – ersetzen Sie dafür im Pfad einfach addresses durch bankData. Der Zugriff erfordert eine gültige Leseberechtigung für Kundendaten.

Beispiel

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
404 Not Found		Das Konto mit `id`=`{accountId}` wurde nicht gefunden. Die Adresse wurde nicht gefunden.

POST customerAccounts//addresses

Mit dieser Methode wird eine neue Adresse für ein bestimmtes Kundenkonto angelegt. Die erforderlichen Felder für die Adresse werden im Request Body angegeben. Die Validierung erfolgt serverseitig, und fehlerhafte Felder werden in der Serverantwort konkret benannt. Der hier beschriebene Endpunkt gilt analog auch für Bankdaten – ersetzen Sie dafür im Pfad einfach addresses durch bankData. Für die Ausführung sind Schreib- und Erstellrechte für Kundendaten erforderlich.

Beispiel

https://www.<ihr-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"
}

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Schreib- und Erstellrechte für Kundendaten.
400 Bad Request		Request body konnte nicht geladen werden. Das Aktualisieren ist fehlgeschlagen.
400 Bad Request	”unknownDataField”	Es wird ein unbekanntes Feld aktualisiert.
400 Bad Request	”invalidFormat”	`custom` ist kein Objekt. `externalId` ist kein String. `labels` ist kein Array oder enthält Nicht-String-Werte.
404 Not found		Die Adresse wurde nicht gefunden.

PUT customerAccounts//addresses/

Mit dieser Methode wird eine vorhandene Adresse eines Kundenkontos aktualisiert. Nur die übergebenen Felder werden geändert, eine vollständige Adressstruktur ist nicht erforderlich. Die Validierung erfolgt serverseitig – fehlerhafte Felder werden in der Antwort ausgewiesen. Der hier beschriebene Endpunkt gilt analog auch für Bankdaten – ersetzen Sie dafür im Pfad einfach addresses durch bankData. Für die Ausführung ist die Berechtigung zum Schreiben von Kundendaten erforderlich.

Beispiel

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

Request Body

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

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kundendaten.
400 Bad Request		Request body konnte nicht geladen werden. Das Aktualisieren ist fehlgeschlagen.
400 Bad Request	”unknownDataField”	Es wird ein unbekanntes Feld aktualisiert.
400 Bad Request	”invalidFormat”	`custom` ist kein Objekt. `externalId` ist kein String. `labels` ist kein Array oder enthält Nicht-String-Werte.
404 Not found		Die Adresse wurde nicht gefunden.

DELETE customerAccounts//addresses/

Mit dieser Methode wird eine Adresse aus einem Kundenkonto gelöscht. Dabei wird überprüft, ob die Adresse tatsächlich zum angegebenen Konto gehört. Der hier beschriebene Endpunkt gilt analog auch für Bankdaten – ersetzen Sie dafür im Pfad einfach addresses durch bankData. Für die Ausführung sind Schreib- und Löschrechte für Kundendaten erforderlich.

Beispiel

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

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Schreib- und Löschrechte für Kundendaten.
404 Not Found		Das Konto mit `id`=`{accountId}` wurde nicht gefunden. Die Adresse wurde nicht gefunden.
409 Conflict		`{accountId}` und die Id des Kontos, zu dem die Adresse gehört, stimmen nicht überein.

Bulk-Methoden

In diesem Abschnitt werden die Bulk-Endpunkte beschrieben, mit denen mehrere Datensätze in einem einzigen Request abgefragt oder verarbeitet werden können.

GET bulk/lastOrderTimestamp

Gibt den Zeitstempel der letzten Bestellung für mehrere Kundenkonten zurück. Ungültige Account-IDs und Konten ohne Bestellungen werden übersprungen. Leserechte für Kundendaten sind erforderlich. Der Pflichtparameter accountId (Integer) gibt die Kundenkonto-ID an und kann mehrfach angegeben werden, um mehrere Konten abzufragen.

Beispiel

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

Antwort

{
    "items": [
        {
            "accountId": 1,
            "lastOrderTimestamp": "2025-01-15T10:30:00Z"
        },
        {
            "accountId": 3,
            "lastOrderTimestamp": "2025-03-20T14:22:00Z"
        }
    ]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.

POST bulk/customerAccounts

Ermöglicht das massenhafte Erstellen und Aktualisieren von Kundenkonten in einem einzigen Request. Der Request-Body ist ein JSON-Array, in dem jedes Element eine Aktion (create oder update) beschreibt. Erstell- und Schreibrechte für Kundendaten sind erforderlich.

Beispiel

https://www.<ihr-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"
        }
    }
]

Antwort

{
    "items": [101, 42],
    "skippedLines": [
        {
            "lineNumber": 3,
            "errorType": "invalidParameters",
            "fieldErrors": {
                "email": {
                    "type": "missing"
                }
            }
        }
    ]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Erstell- und Schreibrechte für Kundendaten.
400 Bad Request	”invalidFormat”	Der Request-Body ist kein JSON-Array oder die maximale Anzahl an Einträgen wurde überschritten.
skippedLines	”invalidParameters”	Pflichtfelder fehlen (z. B. `type`), Feldtyp stimmt nicht überein, ungültiger Wert für `type` (nicht `"create"` oder `"update"`), oder `accountId` fehlt bei `"update"`.
skippedLines	”invalidFields”	Ungültige Felder beim Aktualisieren eines Kundenkontos.
skippedLines	”conflict”	E-Mail-Adresse oder Kundennummer bereits vergeben.
skippedLines	”notFound”	Kundenkonto mit der angegebenen `accountId` wurde nicht gefunden.
skippedLines	”internalError”	Interner Fehler beim Erstellen des Kundenkontos.

POST bulk/customerAccounts/addresses

Ermöglicht das massenhafte Erstellen und Aktualisieren von Kundenadressen in einem einzigen Request. Der Request-Body ist ein JSON-Array, in dem jedes Element eine Aktion (create oder update) für eine Adresse beschreibt. Erstell- und Schreibrechte für Kundendaten sind erforderlich.

Beispiel

https://www.<ihr-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"
        }
    }
]

Antwort

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

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Erstell- und Schreibrechte für Kundendaten.
400 Bad Request	”invalidFormat”	Der Request-Body ist kein JSON-Array oder die maximale Anzahl an Einträgen wurde überschritten.
skippedLines	”invalidParameters”	Pflichtfelder fehlen (z. B. `type`, `accountId`), Feldtyp stimmt nicht überein, ungültiger Wert für `type` (nicht `"create"` oder `"update"`), `addressId` fehlt bei `"update"`, oder ungültige Adressdaten.
skippedLines	”notFound”	Kundenkonto mit der angegebenen `accountId` oder Adresse mit der angegebenen `addressId` wurde nicht gefunden.

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.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Documentation Index

​Unterstützte Methoden

​Datenfelder

​Datenfelder eines Kundenkontos

​Beispiel

​Datenfelder einer Adresse

​Beispiel

​Datenfelder eines Bankkontos

​Beispiel

​Methoden für Kundendaten

​GET customerAccounts

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET customerAccounts/

​Beispiel

​Antwort

​Fehlercodes

​GET customerDataDeleted

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​POST customerAccounts

​Beispiel

​Antwort

​Fehlercodes

​POST customerAccounts//passwordReset

​Beispiel

​Antwort

​Fehlercodes

​PUT customerAccounts/

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE customerAccounts/

​Beispiel

​Antwort

​Fehlercodes

​GET customerAccounts/deleted

​Beispiel

​Antwort

​Fehlercodes

​POST customerAccounts//activate

​Beispiel

​Antwort

​Fehlercodes

​GET customerAccounts//link

​Beispiel

​Antwort

​Fehlercodes

​Methoden für Adressen und Bankdaten

​GET customerAccounts//addresses

​Beispiel

​Antwort

​Fehlercodes

​GET customerAccounts//addresses/

​Beispiel

​Antwort

​Fehlercodes

​POST customerAccounts//addresses

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT customerAccounts//addresses/

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE customerAccounts//addresses/

​Beispiel

Unterstützte Methoden

Datenfelder

Datenfelder eines Kundenkontos

Beispiel

Datenfelder einer Adresse

Beispiel

Datenfelder eines Bankkontos

Beispiel

Methoden für Kundendaten

GET customerAccounts

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET customerAccounts/

Beispiel

Antwort

Fehlercodes

GET customerDataDeleted

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

POST customerAccounts

Beispiel

Antwort

Fehlercodes

POST customerAccounts//passwordReset

Beispiel

Antwort

Fehlercodes

PUT customerAccounts/

Beispiel

Request Body

Antwort

Fehlercodes

DELETE customerAccounts/

Beispiel

Antwort

Fehlercodes

GET customerAccounts/deleted

Beispiel

Antwort

Fehlercodes

POST customerAccounts//activate

Beispiel

Antwort

Fehlercodes

GET customerAccounts//link

Beispiel

Antwort

Fehlercodes

Methoden für Adressen und Bankdaten

GET customerAccounts//addresses

Beispiel

Antwort

Fehlercodes

GET customerAccounts//addresses/

Beispiel

Antwort

Fehlercodes

POST customerAccounts//addresses

Beispiel

Request Body

Antwort

Fehlercodes

PUT customerAccounts//addresses/

Beispiel

Request Body

Antwort

Fehlercodes

DELETE customerAccounts//addresses/

Beispiel

Antwort

Fehlercodes

Bulk-Methoden

GET bulk/lastOrderTimestamp

Beispiel