Manage Customers & Addresses

General

Learn how to get, update and delete customer and their addresses.

Admin API

Get customer

SCAYLE allows you to retrieve a customer by its reference key or ID.

This method can be used to get an existing customer.

This method allows including nested resources using the with parameter.

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

let response = await adminApi.apis.Customers.getCustomer({shopKey: shopKey, countryCode: countryCode, customerIdentifier: customerIdentifier});
let customer = response.body;

Options

Parameter	Type	Required	Description
`with`	string	no	Allows loading nested resources within this request: `addresses`, `legacyCustomData`, `nonUniqueAddresses`.

The nonUniqueAddresses with's value is only available when using the customer ID as identifier.

Update a reference key of a customer

Use this method to assign a reference key to a customer or update existing reference key.

This method can be used to create or update a customer reference key. The existing reference key will be updated in case if a customer was already assigned a reference key.

let response = await adminApi.apis.Customers.updateCustomerReferenceKey({shopKey: shopKey, countryCode: countryCode, customerId: customerId}, {requestBody: customerReferenceKey});
let customer = response.body;

Parameters

Param Name	Type	Required
`referenceKey`	string	true

Update Customer Reference Key

let customerReferenceKey = {
    referenceKey: "my-key"
};

let response = await adminApi.apis.Customers.updateCustomerReferenceKey({shopKey: 'ms', countryCode: 'DE', customerId: 1}, {requestBody: customerReferenceKey});
let customer = response.body;

console.log(customer.referenceKey);

Set Customer Password

This method can be used only if customer's password is known.

Method Signature

await adminApi.apis.Customers.setCustomerPassword(
    {
        shopKey: shopKey,
        countryCode: countryCode,
        customerIdentifier: customerIdentifier
    },
    {
        requestBody: customerPassword
    }
);

Examples

const password = {
  password: 'yourPassword',
  hashingType: 'internal', // internal, external, salesforce
}

// Set password by customer reference key
client.apis.Customers.setCustomerPassword({shopKey: 'ms', countryCode: 'DE', customerIdentifier: "key=my-key"}, {requestBody: password});

// Set password by customer id
client.apis.Customers.setCustomerPassword({shopKey: 'ms', countryCode: 'DE', customerIdentifier: 1}, {requestBody: password});

Set Customer Password Hash

This method can be used for migrating passwords, since usually passwords are stored as hash only.

When setting the hashingType to external, any (empty) password can be submitted. In this case the external service is used and hashing is done on the client side.

Method Signature

await adminApi.apis.Customers.setCustomerPasswordHash(
    {
        shopKey: shopKey,
        countryCode: countryCode,
        customerIdentifier: customerIdentifier
    },
    {
        requestBody: customerPasswordHash
    }
);

Examples

const passwordHash = {
  hash: 'passwordHash',
  hashingType: 'internal', // internal, external, salesforce
}

// Set password hash by customer reference key
client.apis.Customers.setCustomerPasswordHash({shopKey: 'ms', countryCode: 'DE', customerIdentifier: "key=my-key"}, {requestBody: passwordHash});

// Set password hash by customer id
client.apis.Customers.setCustomerPasswordHash({shopKey: 'ms', countryCode: 'DE', customerIdentifier: 1}, {requestBody: passwordHash});

You can also request several customers. We suggest to fine-tune your search, e.g., by combing filter logics and using pagination. As search results are paginated, you can set the amount of customers displayed per page.

This method can be used to get a collection of customers for any given shop and country. It is possible to refine the search by applying filter options.

This method might be disabled by default. Please approach the respective SCAYLE Account Manager for activation.

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

let response = await adminApi.apis.Customers.getCustomers({shopKey: shopKey, countryCode: countryCode});
let customers = response.body.entities;

Examples

let response = await adminApi.apis.Customers.getCustomers({shopKey: 'ms', countryCode: 'DEU'});
let customers = response.body.entities;

customers.forEach(
    customer => console.log(customer.id)
);

Read with Options

let response = await adminApi.apis.Customers.getCustomers({
    shopKey: 'ms',
    countryCode: 'DEU',
    with: 'addresses',
    "filters[id]": "10,11,12"
});

let customers = response.body.entities;

customers.forEach(
    customer => customer.addresses.forEach(address => console.log(address.id))
);

Options

Parameter	Type	Required	Description
`with`	string	false	Allows loading nested resources within this request: `addresses`.
`limit`	integer	false	Maximum number of items in the result. (default: `100`, maximum: `1000`)
`filters[referenceKey]`	string	false	Comma-separated list of reference keys that should be used for filtering.
`filters[id]`	string	false	Comma-separated list of customer IDs that should be used for filtering.
`filters[minId]`	integer	false	Minimum (inclusive) customer ID of entities that should be returned.
`filters[maxId]`	integer	false	Maximum (inclusive) customer ID of entities that should be returned.
`filters[minCreatedAt]`	string	false	Minimum (inclusive) creation date of the customer that should be returned.
`filters[maxCreatedAt]`	string	false	Maximum (inclusive) creation date of customers that should be returned.
`filters[minUpdatedAt]`	string	false	Minimum (inclusive) modification date of customers that should be returned.
`filters[maxUpdatedAt]`	string	false	Maximum (inclusive) modification date of customers that should be returned.
`filters[billingAddressCountryCode]`	string	false	Only returns customers with the given `billingAddress` country code.
`filters[shippingAddressCountryCode]`	string	false	Only returns customers with the given `shippingAddress` country code.
`filters[group]`	string	false	Comma-separated list of customer groups that should be used for filtering.
`filters[isActive]`	boolean	false	Pass true to get only active customers, pass false to get the opposite.
`sort`	string	false	Sort by the provided column. Available values: `id` (default), `appId`, `birthDate`, `firstName`, `lastName`, `lastInvoiceDate`, `lastLoginDate`, `lockedUntilDate`, `passwordResetRequestedAt`, `createdAt`, `updatedAt`.
`sortDir`	string	false	Defines the sorting order: ascending or descending. Available values: `asc` (default), `desc`.

param name	type	description
id	integer	The ID of the customer
referenceKey	string	External reference set by the client to integrate a third-party system.
firstName	string	First name of the customer
lastName	string	Last name of the customer
gender	string	Gender of the customer mentioned as per defined ENUM as "m", "f", "d"
birthDate	string	Date of birth of the customer in YYYY-MM-DD format
email	string	Email address of the customer
phone	string	Phone number of the customer
publicKey	string	Public reference set by the client to display to customers in account areas and transactional emails
title	string	User-defined title. It can be set to NULL otherwise
type	string	Type of customer (like personal)
groups	string	Group to which the customer belongs to
status	CustomerStatus	Defines if the customer is active or not and if the customer is a guest customer or not
company	Company	Company to which the customer belongs to
addresses	CustomerAddress	Customers addresses
legacyCustomData	array	Custom data added to the customer (legacy feature)
createdAt	string	Timestamp when the customer is created
updatedAt	string	Timestamp when the customer is updated

Parameter	Type	Description
`id`	integer	The `ID` of the customer
`referenceKey`	string	External reference set by the client to integrate a third-party system.
`firstName`	string	First name of the customer
`lastName`	string	Last name of the customer
`gender`	string	Gender of the customer mentioned as per defined ENUM as "m", "f", "d"
`birthDate`	string	Date of birth of the customer in YYYY-MM-DD format
`email`	string	Email address of the customer
`phone`	string	Phone number of the customer
`publicKey`	string	Public reference set by the client to display to customers in account areas and transactional emails
`title`	string	User-defined title. It can be set to NULL otherwise
`type`	string	Type of customer (like personal)
`groups`	string	Group to which the customer belongs to
`status`	CustomerStatus	Defines if the customer is active or not and if the customer is a guest customer or not
`company`	Company	Company to which the customer belongs to
`addresses`	CustomerAddress	Customers addresses
`legacyCustomData`	array	Custom data added to the customer (legacy feature)
`createdAt`	string	Timestamp when the customer is created
`updatedAt`	string	Timestamp when the customer is updated

Get customer address

SCAYLE allows you to retrieve specific customer addresses by customer identifier or ID with address identifier. Customer identifiers can be customer ID or customer reference key.

Address identifiers can be address ID or address reference key.

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

let response = await adminApi.apis.Customers.getCustomerAddress({shopKey: shopKey, countryCode: countryCode, customerIdentifier: customerIdentifier, addressIdentifier: addressIdentifier});
let customerAddress = response.body;

Get a customer's address by reference key

let response = await adminApi.apis.Customers.getCustomerAddress({shopKey: 'ms', countryCode: 'DE', customerIdentifier: "key=my-key", addressIdentifier: "key=my-key"});
let customerAddress = response.body;

console.log(customerAddress.id);

List Addresses

This endpoint is not bound to a specific shop country; however, it still requires the shop country details, identified by the shopKey and countryCode, without filtering by the shop country.

Get a list of customer's addresses:

let response = await adminApi.apis.Customers.getCustomerAddresses({shopKey: 'ms', countryCode: 'DE', customerIdentifier: "key=my-key"});
let customerAddresses = response.body.entities;

customerAddresses.forEach(
    address => console.log(address.id)
);

Create new customer address

SCAYLE allows users to create a new address Customer Address. The address might contain a unique reference key, which represents the address.

This method is used to create a new customer address.

let response = await adminApi.apis.Customers.createCustomerAddress({shopKey: shopKey, countryCode: countryCode, customerIdentifier: customerIdentifier}, {requestBody: customerAddress});
let customerAddress = response.body;

Example

Create a customer address

let customerAddress = {
  "referenceKey": "my-key",
  "street": "Domstraße",
  "houseNumber": "1",
  "additional": "first floor",
  "zipCode": "123456",
  "city": "Hamburg",
  "countryCode": "DEU",
  "collectionPoint": {
    "customerKey": "bced-234-234",
    "description": "Kiosk",
    "key": "12345-a",
    "type": "hermes_parcelshop"
  },
  "isDefault": {
    "billing": false,
    "shipping": false
  },
  "recipient": {
    "firstName": "John",
    "gender": "m",
    "lastName": "Doe",
    "title": "Prof."
  }
};

let response = await adminApi.apis.Customers.createCustomerAddress({shopKey: 'ms', countryCode: 'DE', customerIdentifier: "key=my-key"}, {requestBody: customerAddress});
customerAddress = response.body;

console.log(customerAddress.id);

Update a customer address

This method is used to update a customer address reference key.

It will create a new key if the address does not have any existing reference key. Customer identifiers can be customer ID or customer reference key. Address identifiers can be address ID or address reference key.

let response = await adminApi.apis.Customers.updateCustomerAddressReferenceKey({shopKey: shopKey, countryCode: countryCode, customerIdentifier: customerIdentifier, addressId: addressId}, {requestBody: customerAddressReferenceKey});
let customerAddress = response.body;

Examples

Update a customer's address

let customerAddress = {
  "street": "Domstraße",
  "houseNumber": "1",
  "additional": "erste Stock",
  "zipCode": "123456",
  "city": "Hamburg",
  "countryCode": "DEU",
  "collectionPoint": {
    "customerKey": "bced-234-234",
    "description": "Kiosk",
    "key": "12345-a",
    "type": "hermes_parcelshop"
  },
  "isDefault": {
    "billing": false,
    "shipping": false
  },
  "recipient": {
    "firstName": "John",
    "gender": "m",
    "lastName": "Doe",
    "title": "Prof."
  }
};

let response = await client.apis.Customers.updateCustomerAddress({shopKey: 'ms', countryCode: 'DE', customerIdentifier: "key=my-key", addressIdentifier: "key=my-key"}, {requestBody: customerAddress});
customerAddress = response.body;

console.log(customerAddress.id);