Overview

The Customer service provides REST interfaces and functionality supporting the tasks responsible for managing customer accounts. The Customer service supports:

  • Registration for customers to create accounts
  • Sign in and sign out functionality for customers
  • Sessions and authorizations for anonymous users
  • Resetting passwords
  • Core customer profiles, including name and locale preferences
  • Addresses

The Customer service is the master record for customer accounts and profiles. It serves as the central repository of core customer information, such as names, preferences, and addresses. Other services can provide additional data, from order history to near-real-time analytics, that are linked to the central customer record.

By controlling the API access authorization for consumers, the Customer service is the main data source for session information, which is a key piece of any clickstream analysis.


API Reference

/{tenant}

/{tenant}/customers

Manages users for given tenant.

get

Retrieves a list of customers.

Requires scope hybris.customer_read.

post

Create a customer profile (by merchant).

Requires scope hybris.customer_create.

/{tenant}/customers/{customerNumber}

Manages single user for given tenant.

patch

Updates customer profile

Requires scope hybris.customer_update OR hybris.customer_manage.

put

Update customer profile

Requires scope hybris.customer_update OR hybris.customer_manage.

Deprecated

get

Retrieve customer profile by customer number

Requires scope hybris.customer_read.

delete

Deletes single customer for given tenant

Requires scope hybris.customer_update OR hybris.customer_delete.

/{tenant}/customers/{customerNumber}/addresses

Manages addresses of given customer for given tenant.

get

Retrieves a list of addresses of a given customer.

Requires scope hybris.customer_read.

post

Creates an address for a given customer.

Requires scope hybris.customer_update OR hybris.customer_manage.

/{tenant}/customers/{customerNumber}/addresses/{addressId}

Manages single address of given customer for given tenant.

get

Retrieves a single address of a given customer.

Requires scope hybris.customer_read.

put

Updates an address of a given customer.

Requires scope hybris.customer_update OR hybris.customer_manage.

Deprecated

delete

Deletes an address.

Requires scope hybris.customer_update OR hybris.customer_manage.

patch

Updates an address of a given customer.

Requires scope hybris.customer_update OR hybris.customer_manage.

/{tenant}/customers/{customerNumber}/addresses/{addressId}/tags

Manages address tags of given customer for given tenant.

post

Add an array of tags to given address

Requires scope hybris.customer_update OR hybris.customer_manage.

delete

Delete an array of tags from given address

Requires scope hybris.customer_update OR hybris.customer_manage.

/{tenant}/customers/{customerNumber}/accounts

Manages accounts of the customer.

/{tenant}/customers/{customerNumber}/accounts/internal

Adds a new internal account for the customer.

post

Assigning an internal account to an existing customer profile.

Requires scope hybris.customer_updateOR hybris.customer_manage.

/{tenant}/password

Manages customer password.

/{tenant}/password/reset

Handles password reset scenario.

post

Request for password reset token using email id.

Does not require any specific scope.

/{tenant}/password/reset/update

Handles password update after reset.

post

Update password using token

Does not require any specific scope.

/{tenant}/password/change

Handles regular password updates.

post

Change password using old password to authorize password update.

Requires scope hybris.customer_edit_profile.

/{tenant}/me

Manages currently logged-in customer profile.

patch

Updates my customer profile

Requires scope hybris.customer_edit_profile.

get

Retrieve my customer profile

Requires scope hybris.customer_view_profile.

put

Updates my customer profile

Requires scope hybris.customer_edit_profile.

Deprecated

delete

Delete my customer profile and associated accounts

Requires scope hybris.customer_edit_profile

/{tenant}/me/addresses

Manages addresses of currently logged-in customer.

get

Retrieves the list of addresses of the current customer.

Requires scope hybris.customer_view_profile.

post

Creates an address for the current customer.

Requires scope hybris.customer_edit_profile.

/{tenant}/me/addresses/{addressId}

Manages single address of currently logged-in customer.

get

Retrieves details of the given address of the current customer.

Requires scope hybris.customer_view_profile.

put

Updates the given address of the current customer.

Requires scope hybris.customer_edit_profile.

Deprecated

delete

Deletes the given address of the current customer.

Requires scope hybris.customer_edit_profile.

patch

Updates the given address of the current customer.

Requires scope hybris.customer_edit_profile.

/{tenant}/me/addresses/{addressId}/tags

Manages address tags for currently logged-in customer.

post

Add an array of tags to given address

Requires scope hybris.customer_edit_profile.

delete

Delete an array of tags from given address

Requires scope hybris.customer_edit_profile.

/{tenant}/me/accounts

Manages accounts of currently logged-in customer.

/{tenant}/me/accounts/internal

Manages internal account of currently logged-in customer.

post

Sign-up for an internal account, assigning this account to an existing customer profile, created by a 3rd party login. The security mechanism takes care that only an authenticated user with a related, security mechanism verified customer number can assign an internal account to an already existing customer profile.

Requires scope hybris.customer_edit_profile.

/{tenant}/me/accounts/internal/email

Manages changing of customer's own login email address.

/{tenant}/me/accounts/internal/email/change

Handles requests to change customer's own email.

post

Request for changing login email token using current email id and password.

Requires scope hybris.customer_edit_profile

/{tenant}/me/accounts/internal/email/change/confirm

Changes the customer's own email after it is confirmed with a token.

post

Update login email address using token.

Does not require any specific scope.

/{tenant}/me/accounts/{providerId}

Manages social (OAuth) account of currently logged-in customer.

post

Connect a social OAuth provider - Facebook or Google. A client app needs to be configured for each provider to enable OAuth. The OAuth provider Id that denotes one of the supported providers like Facebook or Google.

Requires scope hybris.customer_edit_profile.

delete

Disconnect a social OAuth provider - Facebook or Google. The OAuth provider Id that denotes one of the supported providers - Facebook or Google.

Requires scope hybris.customer_edit_profile.

/{tenant}/signup

Manages customer signup process.

post

Sign-up as a new customer, create a new customer account.

Does not require any specific scope.

/{tenant}/login

Manages customer login process.

post

Login as a customer and request an authentication token. Account is locked and login is not possible when a certain number of failed logins has been recorded. The account is unlocked after a certain amount of time lapsed.

Does not require any specific scope.

/{tenant}/login/{providerId}

Manages social (OAuth) login process.

post

Sign-in using a OAuth provider - Facebook or Google. A client app needs to be configured for each provider to enable OAuth.

Does not require any specific scope.

/{tenant}/logout

Manages customer logout process.

get

Invalidate authentication token - user is logged out.

Does not require any specific scope.

/{tenant}/loginconfig

Manages anonymous access to customer service specific configuration options.

get

Get configuration for (Social) Login providers

Does not require any specific scope.


Events

For more information about events, see the PubSub service documentation.

TopicDescriptionPayloadExample
hybris.customer.password-reset-requestedCustomer requested to reset their passwordschema
{"email":"shopper@yaastest.com"}
hybris.customer.password-updatedCustomer updated the passwordschema
{"email":"shopper@yaastest.com"}
hybris.customer.customer-account-unlinkedA third-party account is detached from the customer profileschema
{"providerId":"facebook"}
hybris.customer.customer-signupCustomer signed upschema
{"email":"shopper@yaastest.com", "providerId":"", "providerAccountId":"", "customerNumber":"CX354CO2", "createdBySeller": true, "createdBy":"user.name@yaastest.com"}
hybris.customer.customer-loginLogin attemptsschema
{"account":"C1423145", "success": true}
hybris.customer.customer-logoutLogout attemptsschema
{"account":"C1423145", "success": true}
hybris.customer.customer-account-linkedA third-party account is attached to the customer profileschema
{"providerId":"facebook"}
hybris.customer.customer-updatedCustomer profile updated by merchantschema
{"customerNumber":"1223", "updatedBy": "user.name@yaastest.com"}
hybris.customer.customer-deletedCustomer profile has been deleted.schema
{"customerNumber":"1223", "email":"user.name@yaastest.com", "triggeredBy":"C1423145"}
hybris.customer.address-createdAddress createdschema
{"account":"C1423145"}
hybris.customer.address-updatedAddress updatedschema
{"account":"C1423145"}
hybris.customer.address-deletedAddress deletedschema
{"account":"C1423145"}
hybris.customer.address-tag-addedAddress taggedschema
{"account":"C1423145"}
hybris.customer.address-tag-deletedAddress tag deletedschema
{"account":"C1423145"}
hybris.customer.customer-login-email-changedCustomer changed his/her login emailschema
{"customerNumber":"C1223", "oldEmail": "old.email@yaastest.com", "newEmail":"new.email@yaastest.com"}


Storing Customer Addresses

The customer address is an integral part of the customer data because it is embedded in the customer profile. There are several endpoints that enable you to perform operations on customer addresses:

  • /{tenant}/customers/{customerNumber}/addresses: You can get all addresses for a specific account. You can also create a new address for any customer account.
  • /{tenant}/customers/{customerNumber}/addresses/{addressId}: You can retrieve an address by its id provided in the URL as the {addressId} path parameter value. You can also update or delete an address.
  • /{tenant}/me/addresses: You can create and retrieve your own addresses.
  • /{tenant}/me/addresses/{addressId}: If you have several addresses, you can retrieve a specific one by its id. You can also update and delete a specific address.

Customer addresses are stored in the customer profile data as a list. The first created address for a customer is always the default, even when it is explicitly specified as not default.

{
  "customerNumber": "C123456",
  "title": "Dr.",
  "firstName": "Max",
  "middleName": "Simon",
  "lastName": "Muster",
  "contactEmail": "noreply@yaastest.com",
  "contactPhone": "+1 1111 2222 3333",
  "company": "hybris",
  "preferredLanguage": "en_US",
  "preferredCurrency": "USD",
  "addresses":
    [
      {
        "id": "53426fc4e4b08806bb0d3ecc",
        "contactName": "Business",
        "street": "Musterstrasse",
        "streetNumber": "42",
        "city": "Munich",
        "country": "DE",
        "isDefault": "true",
        "tags": ["home"]
      },
      {
        "id": "53442904e4b08806bb0d4243",
        "contactName": "Joe Smith",
        "companyName": "Cargo Services Airfreight",
        "street": "Cheng Xiang Zhen Guan Tang Lu",
        "streetNumber": "1031",
        "extraLine1": "No. 2058",
        "extraLine2": "Suzhou City",
        "zipCode": "201202",
        "city": "Taicang City",
        "state": "Jiangsu Province",
        "country": "CN",
        "contactPhone": "+86 182 9349 4663",
        "isDefault": "false",
        "tags": ["shipping", "billing"]
      }
    ]
}

Extending a customer address with a mixin

Each customer address can be enriched with additional custom attributes that extend the customer address definition on a need-to-have basis. This is where mixins can be used. Mixins help you define an additional property or set of properties you can add in, such as your customer address definition. In this case, the default customer address information is extended with a mixin-based property for secondary contact phone.

{
  "id": "53426fc4e4b08806bb0d3ecc",
  "contactName": "Joe Smith",
  "companyName": "Cargo Services Airfreight",
  "street": "Cheng Xiang Zhen Guan Tang Lu",
  "streetNumber": "1031",
  "extraLine1": "No. 2058",
  "extraLine2": "Suzhou City",
  "zipCode": "201202",
  "city": "Taicang City",
  "state": "Jiangsu Province",
  "country": "CN",
  "contactPhone": "+86 182 9349 4663",
  "isDefault": "false",
  "tags": ["shipping", "billing"],
  "metadata": {
    "mixins": {
      "secondaryContactPhone": "<%- @partial('proxy_url') %>/hybris/schema/v1/kiwistest/contact-number.json"
    }
  },
  "mixins": {
    "secondaryContactPhone": {
      "number": "+86 334 0033 9934"
    }
  }
}

Customer address autosave

When an order is placed with a billing or a shipping address:

  • If the addresses did not previously exist in the customer address book, they are added to the customer's address book.
  • If the address already exists, then the attributes that are not considered to check for equality are merged. Addresses are equal if everything except the tag and mixins match.
  • The merging of the attributes does not replace the existing value. For example, if a mixin contains an additionalCode property and the new address also contain the same entity but with a different value, then the previous value remain intact.

Following is an example of a mixin:

"mixins":{
  "additionalCode":{
    "code":"abc"
  }
}

Following is a mixin with additional information:

"mixins":{
  "additionalCode":{
    "myKey":"xyz"
  },
  "houseInfo":{
     "color":"white"
  }
}

If the two are merged, only the new mixin houseInfo is added with its value whereas the additionalCode mixin remains intact. Therefore, the result of the merge would be:

"mixins":{
  "additionalCode":{
     "code":"abc"
  },
  "houseInfo":{
     "color":"white"
  }
}


Extend Customer Information

Customers can be defined by a set of properties, such as contactEmail or customerNumber, that uniquely identify a customer for the external world.

However, these schema-based properties are few and are very common to all customers. However, mixins can help you to define a set of additional properties once and reuse them in many different customer definitions. You can assign one mixin to many customers, but you can also use many mixins to extend the information about one customer.

In the Customer service, mixins are supported by the following methods and endpoints:

  • POST /{tenant}/customers
  • GET, PUT /{tenant}/customers/{customerNumber}
  • GET, PUT /{tenant}/me

In the case of GET requests in the Customer service, the expand query parameter can handle the mixins. By default, no mixins are returned. There are two options to include a mixin in the response:

  • mixin:* - To expand the parameter value, which will return all defined mixins.
  • mixin:<mixin name> - To expand the parameter value, which will return only the mixin with the name <mixin name>. However, you can use mixin:<mixin name> multiple times, such as expand=mixin:mixin1,mixin:mixin2.

Mixin schema

Mixins define a set of properties you can add in your customer definition. The mixin itself is supported by the Schema service and is always referred from other services by a URL. The schema is used to validate the contents of the mixin and is also a unique namespace identifier for the mixin. Following is an example of the mixin structure:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Color Schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "red": {
      "type": "number"
    },
    "green": {
      "type": "number"
    },
   "blue": {
      "type": "number"
    }
  },
  "required": ["red", "green", "blue"]
}

Mixins declare the properties and data types of these properties. In this example, there are three colors defined, each of which is designated by a numerical value.

With this mixin in the Schema service, you can use it to extend any kind of customer information with these additional properties. These properties are not part of the Customer schema, they are part of the mixin schema.

The service assumes that the schema content is immutable. If the schema referenced by a URL change, you can expect some unpredictable results. You should only use schemas hosted in the https://api.beta.yaas.io domain.

Mixin data

Each mixin is a named JSON fragment with an associated JSON Schema. In this example, it is a color. The metadata attribute specifies which mixins can be included. To include a mixin with a name color, the metadata.mixins.color attribute must declare a schema for the mixin. When you create a new customer or update any customer with new information, you can add these mixin-based properties to the whole customer configuration.

{
  "name": "John",
  "metadata": {
    "mixins": {
      "color": "https://api.beta.yaas.io/hybris/schema/v1/tenant/color.json"
     }
  },
   "mixins": {
     "color": {
        "red": 15,
        "green": 34,
        "blue": 255
        }
    }
}

Important notes about this example:

  1. You must always add the metadata property that defines the mixin alias and binds it to the URL to the mixin JSON-formatted definition. You create the alias as you like. What is important is that when you use the mixin, you always take the mixin alias you defined in the metadata section.
  2. You must have the mixins property, which can have properties from multiple mixins, each one referred by its alias. In this example, there is only one color mixin, and it has only three properties.

Mixin validation

The service validates that the mixin data adheres to the schema. If the mixin does not validate, or if there is no schema declaration for a mixin, a validation is returned with an HTTP status code of 400, with detailed information is available in the response body.


Scopes in the Customer Service

Scopes enable you to specify the permissions that are required to access resources and operations in the Customer service.

The following table includes all of the scopes supported by the Customer service.

ScopeDescription
hybris.customer_createUse this scope to create a new customer account, such as merchants or sellers.
hybris.customer_readUse this scope to read customer profiles or retrieve a list of customers.
hybris.customer_update OR hybris.customer_manageUse this scope to update customer profiles.
hybris.customer_deleteUse this scope to delete customer profiles.
hybris.customer_view_profileThis scope is granted to customers during login. Use this scope to access the profile of the logged-in customer.
hybris.customer_edit_profileThis scope is granted to customers during login. Use this scope to modify the profile of the logged-in customer.

For more information about the authorization and authentication used in SAP Hybris services, and also about the scopes in general, see:


Preferred Site Support

The Storefront can support multiple sites, so customers can save their preferred site in their profile using the attribute preferredSite.

  • For Authenticated Users: This attribute can store one of the site codes (identifiers) that are stored in the Site service configuration for the sites.
  • For Anonymous Users: A default site will be used.

Additionally, the authenticated users who do not have a configured preferred site will also have the default site set as their preferred site.


Email Notification Options

At some occasion, the Customer service sends an email notifications to customers. This may happen, for example, when a customer changes email address and the service sends an email notification asking for confirmation.

Using Builder, it is possible to set email configurations which is used by customer service when sending notifications to customers. Let's take a look at the available configuration keys and what kind of values they can hold:

  • cust.notification.email.from.name: The name of the email sender. If this value is not set explicitly in Builder, it will have the default value: noreply@{tenant}.mail.yaas.io. For example, for kiwiscitest tenant, the default value will be noreply@kiwiscitest.mail.yaas.io.
  • cust.notification.email.from: The email address of the sender. The value can consist of alphanumeric characters, however special characters are not allowed. It can be set to: null.
  • cust.notification.email.replyToName: The name of the sender to be used as the receipient name during email reply.
  • cust.notification.email.replyTo: The sender's email address to be used as the receipient email address during email reply. The value can consist of alphanumeric characters, whereas special characters are not allowed. It can be set to: null.

The values of these keys are set either in Commerce Settings section of the Builder module or they can be directly set by using the API of the Configuration service.


Create New Account

As a customer, you can sign up to create a new account.

Request

To create an account, you need:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/signup
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}: The name of the current tenant.

Body

To sign up for a new account, you must provide an email and password:

  • email: A valid email address
  • password: A minimum of six characters

This is an example of the format of the request body:

{
    "email": "user@yaastest.com",
    "password": "secret"
}
Validation

The service provides methods to avoid possible issues and provide feedback. For example:

  • If you try to create an account using an email address that already exists, the error message User email must be unique is returned.
  • If you try to set a password that does not comply with the minimum requirements, an error is generated with feedback information.
  • A validation mechanism checks if the email format is correct.

Response

After you successfully create a new account, you receive a confirmation consisting of three parts:

  • Status code: 201
  • Header:
    • Location: Contains a string value. For example: https://api.beta.yaas.io/hybris/customer/v1/dummyTenant/me
  • Body: The body returns the id value, which is used to uniquely identify the account. For example:
    json { "id": "536cd455cb4e6cc7d8f50165" "link": "https://api.beta.yaas.io/hybris/customer/v1/dummyTenant/me" }


Create Customer without Email

You can create a customer profile without specifying an email address. The hybris.customer_create scope is required. To create a customer profile without an email, you need:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.

The body may contain some basic customer data. However, the contactEmail attribute is not needed in this scenario. For example:

{
    "firstName": "John Smith",
    "company": "example_Company",
    "preferredLanguage": "en_UK",
    "preferredCurrency": "GBP"
}

As a response, a customer id and the link to the resource are returned:

  • "id": "CO139024732"
  • "link": "https://api.beta.yaas.io/hybris/customer/v1/dummytenant/customers/CO139024732"

If you now retrieve this customer by id, the returned customer record does not contain the contactEmail attribute. These customer records cannot be used to log in to a storefront until the merchant adds the account information to the customer profile.

If there is no contactEmail provider for the customer, then no internal account is created for the customer. If you retrieve the customer with the expand parameter set to accounts, such as https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/CO139024732?expand=accounts, the response will be similar to the example below:

{
    "firstName": "John Smith",
    "company": "example_Company",p
    "preferredLanguage": "en_UK",
    "preferredCurrency": "GBP",hybris
    "accounts": [],
    "customerNumber": "CO139024732",
    "id": "CO139024732"
}


Add Internal Account to Customer

It is possible to have a customer profile that does not have any internal account assigned. For example, a customer may have been created without an email or with the help of an external account such as Facebook. However, you can always create an internal account for such a customer later. To do so, a proper scope is required. You can read more about the scopes in the Scopes in Customer Service section.

Adding an internal account

In the following example, there is a customer with a Facebook account, but no internal account. You can retrieve this customer using the expand parameter set to accounts: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/CO139024732?expand=accounts.

The customer profile looks like the example below, where only the external Facebook account is connected to the profile:

{
    "preferredLanguage": "en_UK",
    "preferredCurrency": "GBP",
    "accounts": [
       {
            "providerId": "facebook",
            "id": "10205575494848716"
       }
    ],
    "customerNumber": "CO139024732",
    "id": "CO139024732"
}

To add an internal account, use the request URL https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/CO139024732/accounts/internal.

The message body must contain an email associated with the customer. For example:

{
    "email": "John_Smith@yaastest.com"
}
All internal accounts must be unique. You can only create one internal account for a single email address.

The customer number is returned in the response:

{
    "ID": "CO139024732"
}

Now, if you retrieve the customer with the expand parameter set to accounts, such as https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/CO139024732?expand=accounts, you get something similar to the example below, which shows that the additional internal account has been added to the customer profile, as well as the contact email:

{
    "preferredLanguage": "en_UK",
    "preferredCurrency": "GBP",
    "accounts": [
       {
            "providerId": "facebook",
            "id": "10205575494848716"
       },
       {
           "id": "John_Smith@yaastest.com"
       }
    ],
    "customerNumber": "CO139024732",
    "id": "CO139024732",
    "contactEmail": "John_Smith@yaastest.com"
}
  • The email used to create an internal account for a customer is used as a customer login.
  • A password reset token is generated and sent to the user.
  • If the query parameter ?sendPasswordResetNotifications=false is given, then no reset token is generated, and the PubSub event to notify about a password reset is not sent.

 


Update Customer Profile

Merchants can update the profile data of a customer using a simple PUT request. You can modify almost any customer property, with the exception of customerNumber. To update a customer profile, a proper scope is required. You can read more about the scopes in the Scopes in Customer Service section.

Request

To update a customer profile, you need:

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customer/{customerNumber}
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}: The name of the current tenant.
    • {customerNumber}: The unique identifier of the customer.

Body

In the following example, you will update a customer's preferred language.

  1. Following are the properties for an existing customer.
    {
     "firstName": "Jack",
     "lastName": "Williams",
     "contactEmail": "noreply@yaastest.com",
     "preferredLanguage": "en_UK"
    }
    
  2. To change the preferred language for the customer, you need to send the properties that you want to update in the request body. You do not need to send any other properties.
    {
     "preferredLanguage": "de_DE"
    }
    
  3. If you now retrieve this customer's profile data, the properties have been modified.
    {
     "id": "C8685677011",
     "customerNumber": "C8685677011"
     "firstName": "Jack",
     "lastName": "Williams",
     "contactEmail": "noreply@yaastest.com",
     "preferredLanguage": "de_DE"
    }
    

Validation

This feature includes a validation mechanism. For example, if you used the following invalid data to update the preferredLanguage property of a customer, the update would fail:

{
    "preferredLanguage": "der_DERq"
}

If validation fails, an error code of 400 is returned.

Response

A successful response includes a status code of 200.


Get All Customer Accounts

Merchants with the proper scope can view all customer accounts in a particular tenant.

Request

To get all customer accounts, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}: The name of the current tenant.

You can use several query parameters to modify the results:

  • Expanding: Use the expand parameter to include additional customer information.
  • Paging, filtering, sorting: You can add additional query parameters to your request. This works as a filter according to specific fields. Use these parameters to:
    • Set the number of items to be displayed on one page.
    • Filter your results by selected fields.
    • Sort the results.

For more information about query parameters, see Use Query Parameters.

Response

A successful response includes a status code of 200 to indicate that the list of customers has been successfully retrieved.

Also, if you set the totalCount query parameter to true in your request, the header that contains the total number of results is returned. This example is a use case for results consisting of two entries.

[
    {
      "email": "muster@yaastest.com",
      "name": "Max Muster",
      "type": "BUYER"
    },
    {
      "email": "john.doe@yaastest.com",
      "name": "John Doe",
      "type": "BUYER"
    }
]

If there are a significant number of results, the query parameters provide convenient tools to better organize the search results. For more information about query parameters, see Use Query Parameters.


Get Specific Customer Account

Merchants can retrieve the details of any customer account in a particular tenant. The request body does not need to contain any information. All the necessary data is sent together with the query parameter and message headers.

Request

To get a customer account, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/{customerNumber}
    Each customer is given an identifying number. You can use this number in your query to retrieve the account data of a single customer.
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {customerNumber}: The unique identifier of the customer.
  • Query Parameters:
    • expand: You can use this parameter to include additional customer information. For more information about this parameter, see Expanding Customer Information.

Response

A successful response includes a code of 200.

The successful response contains the requested customer profile data. For example:

{
         "customerNumber": "C123456",
        "firstName": "Joe",
        "lastName": "Doe"
}


Use Query Parameters

You can use several query parameters to influence the way your results are displayed. You can control the sort order and the number of results displayed per page. You can also apply filters based on the selected attributes.

Paging results

You can set parameters for paging results for methods that return more than one value, such as a GET applied on the https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers resource. There are two parameters that can be used for paging results:

  • pageSize: Defines the number of result entries allocated to one page. If there are more results than a single page can hold, additional pages become available.
  • pageNumber: Defines the page number to be retrieved. Page numbering starts with 1.

URL example

This example displays three accounts per single page, and the third page of results is displayed: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/?pageNumber=3&pageSize=3

Sorting results

You can set parameters to filter the results for methods that return more than one value, such as a GET applied on the https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers resource. You can sort the results using the product attributes as a sort criteria. To sort the results, append one or more sort properties to the URL. By default, the values are sorted in an ascending order. However, this can be changed. For example, sorting by email:

  • Ascending: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers?sort=email:asc
  • Descending: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers?sort=email:desc

You can sort the results by more than one criterion. To do so, use the list of the comma-separated properties.

Filtering results

You can set parameters to filter results for methods that return more than one value, such as a GET applied on the https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers resource. Generally, using a GET method on the https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers resource returns all existing customer accounts. However, you can limit the number of results by providing certain parameters.

URL example

This example query displays all accounts belonging to customers with the name John Smith:

https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/?q=name:"John Smith"

Total count of results info

This is a Boolean value you can use to determine if the total count of the results should be returned together with the response.

URL examples

  • https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/?totalCount=false
  • https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/?totalCount=true

Expanding customer information

When you retrieve customer data, you can include additional customer information, such as accounts or addresses. To do so, you need:

  • Method: GET
  • Query Parameter: expand
  • Resources:
    • /{tenant}/customers: Get extended data for all customers.
    • /{tenant}/customers/{customerNumber}: Get extended data for a specific customer.
    • /{tenant}/me: Get extended data for your own customer profile.

The expand parameter accepts several values:

  • accounts: Returns customer profile information and a list of customer accounts, both social and internal.
  • addresses: Returns a list of all customer addresses associated with the customer profile.
  • defaultAddress: Returns a separate defaultAddress property that contains a single default address. If a default address does not exist, this property is not provided.
  • mixin:name: Returns the information that has been defined in the mixin specified by its name.
  • mixin:*: Returns the customer-related information that has been defined in mixins.

These comma-separated values can be used. For example:

  • https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers?expand=accounts,defaultAddress
  1. By default, the customer profile is always returned with accounts data.
  2. By default, addresses and defaultAddress are not returned. To get this data together with customer profile data, you must use the query parameter with the appropriate value, such as expand=defaultAddress.
  3. By default, there is no mixin information that can be returned with the customer data.


Customer Login

Customers with accounts can log in to create and place orders, modify their profiles, and select a payment method.

Request

To log in, you need:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/login
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}: The name of the current tenant.

Example

In the message body, put an email address and password as shown in this example:

{
    "email": "name.surname@yaastest.com",
    "password": "secret"
}

Response

A successful response includes a status code of 200 and the authentication token as shown in this example:

{
    "accessToken": "6fc4e4b08806b0d3ec"
}


Change Login Email

There are many reasons your customers may want to change their login email. Your task is to make sure the process is easy and safe. You do not let your customers simply change their login email unless they are verified and consciously confirm they understand what they do. Here is an example of how this goal is achieved:

  • When a customer changes the login email, the customer is asked to provide the account password to confirm the email change.
  • Once the customer has confirmed the email change by providing the account password, a confirmation email containing a link to confirm is sent to the new email address provided in previous step. Also a notification email is sent to the old address.
  • Now, the customer should click the link included in the email to do the final confirmation of the login email change. Only after this, the login email address is updated in the system.

Two-step operation

There are two endpoints involved in the whole operation:

  • One used to send a request for login email change
  • One used to update the login email, after the request has been confirmed

Let's go through them one by one.

Request for login email change

First, a customer should make a request to change the login email. To make such a request, the following endpoint /{tenant}/me/accounts/internal/email/change should be used. Scope: hybris.customer_edit_profile is required to make this request.

The request payload carries the following information: email, password, and newEmail. Let's see an example:

{
    "email" : "noreply@yaastest.com",
    "password": "s3cr3t",
    "newEmail" : "pleasereply@yaastest.com"
}

In the payload, all fields are mandatory. If the operation is successful, the 204 status code is returned. If the specified newEmail already exists, the 409 status code is returned.

Let's take a closer look at what actually happens during this operation:

  • After the request is successfully made, an email is sent to the customer's new email address, that has been provided in the newEmail field.
  • The email contains the confirmation URL. The URL must be configured by the tenant in the Configuration service.
  • The configuration key is customer.changeemail.redirecturl. That is where the URL should be stored.
  • Now, take a look at the link: http://www.example.com/confirmChangeEmail.html?token={token}
  • The {token} in the URL above should be replaced by the generated token.
  • The token mentioned above is valid only for 24 hours.

Confirm the change of the login email

The customer can confirm the changing of the login email address by making a POST request to the endpoint /{tenant}/me/accounts/internal/email/change/confirm with a token in the payload. No scope is required to make this request. As soon as the customer confirms, the login email is changed.

The POST request consists of a simple payload that carries a valid token. As mentioned before, this token is valid only for 24 hours. After it expires, customers are no longer able to use it to change the login email.

{
    "token" : "aCd35CzsAhKt6mKcfCVef54YvfdsfbewFaCd35CzsAhKt6mKcfCVef54YvfdsfbA"
}

In the token field, in the payload, is mandatory. If the operation is successful, the 204 status code is returned.

After a customer confirms and the service updates the login email, a hybris.customer.customer-login-email-changed event is fired. The event payload consists of the following information:

  • Customer number
  • Old email address
  • New email address

Synchronization of the login email and contact email

Optionally, you can also synchronize the existing contact email with a new login email by providing an additional, optional property in the payload. Let's see an example:

{
    "email" : "noreply@yaastest.com",
    "password": "s3cr3t",
    "newEmail" : "pleasereply@yaastest.com",
    "syncContactEmail": "true"
}

The first three properties are obligatory and have been presented in the sections above. The syncContactEmail property, however, is a new one here. It accepts a boolean value, true or false:

  • If the property is set to true, then the contact email will be set to the new login email address after the login email is changed successfully. In other words, the contact email will be identical with the login email, after the login email change is confirmed.
  • If the property is absent or it is set to false, then the contact email is not modified and only the login email address will be changed.


OAuth Logins

You can sign in using supported OAuth providers. This table shows the providers that are currently supported.

ProviderProvider ID
Facebookfacebook
Googlegoogle
YaaSyaas

If the OAuth provider uses an email address to identify the person signing in it will be stored in the corresponding customer profile as contact email address. This is the case for Yaas. There is a time limit of 10 seconds after which an attempt to sign in a user via a social account will be aborted by the service.

Request

To use OAuth2 authorization, you must configure your client application for each provider.

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/login/{providerId}

In the request body, put the accessToken your application receives from the social login provider, such as Facebook:

{
   "accessToken": "BgQ75HNivPQ6TTrvwIrsuqSM2iENjhvu"
}

Response

A successful response includes a status code of 200 and the new authentication token from the Customer service that you can use to sign in. This is an example of a response:

{
    "accessToken": "6fc4e4b08806b0d3ec"
}


Activate Customer Profile

When a customer creates a profile, the profile is active immediately by default. This can be modified later by a merchant. A merchant can deactivate any customer by updating the customer profile. Deactivated customers cannot:

  • Log in to the tenant
  • Reset their passwords

Request

To deactivate or activate a customer profile, you need:

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customer/{customerNumber}
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters:
    • {tenant}: The name of the current tenant.
    • {customerNumber}: The unique identifier of the customer.

Merchants can activate or deactivate a customer profile by changing the value of the active property. Technically, it can be described as updating the customer profile, where the only updated property is the active property.


Modify Password

You can update your password using a token or your old password for authorization.

Password update

To update a password, use:

  • Request URL: /{tenant}/password/update
  • Method: POST

You must put these required entries in the request body:

  • token: Password reset token that was sent via email
  • password: New password

A successful response includes a status code of 204, which means the password has been updated successfully.

Password change

To change a password, use:

  • Request URL: /{tenant}/password/change
  • Method: POST

You must put these required entries in the request body:

  • email: The email address associated with the account for which the password is being changed
  • currentPassword: Current valid password
  • newPassword: New password to be set

A successful response includes a status code of 204, which means the password has been changed successfully.


Reset Customer Password

Customers can reset their passwords to regain access to their accounts. The workflow for this process is similar to this example:

  1. After a customer requests to reset their password, an email is sent that includes a link and a token to reset their password. The token can only be used once and is only valid for a short period of time, such as 24 hours.
  2. The customer clicks the link in the email and the service takes care of the rest using the POST method, URL, and the body content presented in the example.
  3. The link that points to the password reset form can be set up in the Configuration service with the help of the key customer.passwordreset.redirecturl. This is an example link: http://www.example.com/resetPasswordForm.html?token=

Request

To reset the customer password, you need:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/password/reset
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}: The name of the current tenant.

Example

  1. Customers provide their unique identifier in the tenant. In this example, it is an email address that is unique to the tenant. The password-reset request is similar to this example:
    {
     "email": "noreply@yaastest.com"
    }
    
  2. Response to the successful request includes a code of 204 with no content.


Manage Social Logins

Add a social login

Customers can add social account logins to their account profiles. The process of adding social logins is controlled. For example:

  • If the social login is already associated with a different profile, the request is rejected.
  • The user must be authenticated to add a login to the profile.
Adding a new social login to an existing account is similar to the initial signup through the social login provider, but it honors the fact that the customer is already logged in.

Remove a social login

If you no longer need a social account to access your profile, you can remove it. In other words, you can disassociate your profile account from the social account login. There are several potential situations you may encounter when disconnecting a social account from your profile:

  • You have several social logins associated with your profile.
  • You have only one social login in the profile. In this case, the operation generates an error.
  • You tried to remove a social login that does not exist in the profile. This generates an error.

Removing a social login

In this example, you have several social account logins, including a Facebook login. You want to unlink the Facebook account login from your profile. To do so, you need:

  • Method: DELETE
  • Request URL: /{tenant}/me/accounts/facebook
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters:
    • {tenant}: Name of the current tenant.
    • {providerId}: Social account identifier, in this case facebook.

A successful response includes a status code of 204 No Content. This indicates that the server has successfully processed your request. The service does not return any content here. Any other social logins previously assigned to the customer profile remain unchanged.

After you have disassociated a social account login from your customer profile, you can no longer use this social login to access your profile.

Removing the last social login

In this example, you only have a Facebook account login linked to your customer profile and you want to remove this login. No other social account logins exist in your profile.

You perform the same operation as shown in the previous Removing a Social Login section, using the same methods, resource, headers, and other data. However, you cannot remove the last social login from your profile. If you try to do this, you receive the following error:

  • status code: 400 Bad Request
  • Response Body: Contains an error message that provides these elements:
    • Type of error
    • Status code number
    • Error description

The result is that the last social account login for a customer profile cannot be deleted.

Removing a non-linked social login

In this example, you do not have any social account logins associated with your customer profile. However, if you try to remove the Facebook social login, an error is generated. See the Removing a Social Login and Removing the Last Social Login sections for details about the operation and a possible error explanation.

See social logins connected to an account

As a customer, you can see all social account logins associated with your profile. In this example, you create a new account:

  1. Log in using the Customer service with a social login provider, such as Facebook:
    • https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customer/login/facebook
    • POST
    • Body contains the accessToken
    • Headers provide authorization
  2. As a response, you get the accessToken that is associated with the social account login that has just been created and the corresponding profile that is assigned to this social account.
  3. The profile and social account login have been created. Now, you access the Customer profile and see the social account login assigned to your profile. To do so:
    • /me
    • GET
    • Authorization: You must provide a proper manage scope that enables the user to perform these operations. For example, you can use an Authorization header to send a valid OAuth 2.0 access token for authorization purposes.
  4. A successful response includes a status code of 200 and this message body:
    {
    "id": "accessToken for social login",
    "customerNumber": "Customer Number",
    "preferredLanguage": "en_US",
    "preferredCurrency": "USD",
    "oAuthProviders": [
      "Facebook": "Facebook App ID"
    ]
    }
    
  5. In the response, you can see the assignment of Facebook together with the Facebook app ID. It is assigned to your customer profile as one of the social account login providers that can be assigned to the profile.
  6. In this way, you can see all social login providers assigned to the customer profile. The list includes all assigned accounts and their types.


Retrieve Social Login Configuration

The Customer service can provide the social media login configuration in response to the request received from the storefront application. The response from the Customer service includes a Facebook App Id and a Google Client Id.

Both identifiers can be used for social login from the storefront application. This does not require any other authentication, so social login configuration is accessible for anonymous users.

The values for these two fields are to be set in the Configuration service, which is responsible for the management of the tenant and project related configuration.

The values can be provided via the Builder.

The keys are: facebook.app.id and google.client.id.

Request

To retrieve the configuration for the social media login providers, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/loginconfig

Response

A successful response includes:

  • status code: 200
  • Response body: A JSON-formatted message containing all retrieved social media identifiers.
    {
    "facebookAppId" : "1112225435398760",
    "googleClientId" : "123424689777-git5emebgh3to7p1gscq2j9etsvmds4i.apps.googleusercontent.com"
    }
    

If a Facebook App Id or Google Client Id has not been set, then it is omitted from the response. If neither is set, then the response is an empty object.


Delete a Customer Profile

The Customer service allows customers to delete their profiles and associated accounts. A customer must be signed in to delete the profile and account from the Customer service. Here is the process for deleting a customer profile and account.

Request for the profile deletion

When the customer requests to delete the account, send a DELETE request to the {tenant}/me endpoint

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/me
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}: The name of the tenant.
  • Scope: hybris.customer_edit_profile

Response status code for successful request is 204.

After a successful deletion request:

  • The service sends an email to the customer, asking for the confirmation of the deletion
    • The email contains a link with a token that the customer needs to open in order to confirm the deletion
    • The token, in the link, is valid for 24 hours
  • The email, asking for the confirmation of the deletion, is sent to:
    • The sign-in email (username), if the customer has an internal account
    • The contactEmail, if the customer does not have an internal account but the contactEmail is set
    • Otherwise, the account is simply deleted without any confirmation email

Confirmation of the profile deletion

A customer can confirm the deletion of the profile by sending a DELETE request with the token (received in the email) as a query parameter:

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/me?token={token}
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}: The name of the tenant.
  • Query parameter:
    • token={token}: {token} is the token sent in the email asking for the confirmation.

If successful, the Customer service responds with a 202 Accepted message.

The service deletes the customer's data asynchronously, in the background. That means that the deletion may happen after a short delay. As soon as the service accepts the delete request, the service fires the hybris.customer.customer-deleted event. The payload of this event includes the customerNumber and email address of the deleted customer, and the information who actually requested deletion - in this case it is the customer.

A sample payload of a customer-deleted event:

{
  "customerNumber" : "C0123456789",
  "email" : "user.name@yaastest.com",
  "triggeredBy" : "C0123456789"
}


Delete a Customer Profile As Merchant

The Customer service now allows merchants to delete customer profiles and associated accounts. Here is the process for deleting a customer account.

Request for the profile deletion

When the merchant requests the deletion of a customer profile, he sends a DELETE request to the /{tenant}/customers/{customerNumber} endpoint.

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/customer/v1/{tenant}/customers/{customerNumber}
  • Authorization: You must provide a proper scope that enables users to perform these operations. The scopes should be granted in an access token from OAuth 2.0 service. For more information about the authorization and authentication used in hybris services, see Authorization.
  • URL Path Parameters
    • {tenant}
    • {customerNumber}
  • Scope: hybris.customer_update OR hybris.customer_delete

Response status code for successful request is 202 Accepted.

The service deletes the customer data asynchronously, in the background, and therefore no further action or communication is required. As soon as the service accepts the delete request, it fires the hybris.customer.customer-deleted event. The payload of this event contains the customerNumber and, if available, the email' of the customer that is being deleted. Additionally, it contains thehybris.user` that requested the deletion.

A sample payload of a customer-deleted event:

{
  "customerNumber" : "C0123456789",
  "email" : "ibuyalot@yaastest.com"
  "triggeredBy" : "yaastest"
}


Error Types

For information about error codes, see the API Reference.


Glossary

TermDescription
mixinCustomizable definition of additional properties for the customer. One customer definition can use many mixins, and one mixin can be used by many customer definitions.
tenantA tenant is a group of users on a project sharing common access, with specific privileges to a service.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.