Engagement Center Customer

Overview

The Engagement Center Customer Service SDK is a mashup service that is used by merchants for managing customer master data. This service is built on top of the Customer service and only exposes some endpoints that are used by merchants. For more information about the Customer service, see Customer.

Using this service, you can:

  • Create customers.
  • Update customers.
  • Retrieve customers.
  • Manage ERP customers for automatic deletion.


API Reference

/{tenant}/customers

Manage customers for a given tenant.

/{tenant}/customers

post

Create a customer.

Required scope: hybris.cecentercustomer_manage

get

Retrieve a list of customers.

Required scope: hybris.cecentercustomer_view

/{tenant}/customers/{customerNumber}

Manage a single customer for a given tenant.

/{tenant}/customers/{customerNumber}

put

Update the customer profile.

Required scope: hybris.cecentercustomer_manage

get

Retrieve a customer by customer number.

Required scope: hybris.cecentercustomer_view

delete

Deletes single customer for given tenant.

Required scope: hybris.cecentercustomer_manage

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

Manages accounts of the customer.

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

post

Assigning an internal account to an existing customer profile.

Requires scope hybris.cecentercustomer_manage

/{tenant}/customers/{customerNumber}/socialMediaUsers

Manage social media users for a given tenant.

/{tenant}/customers/{customerNumber}/socialMediaUsers

get

Retrieve all the social media users with the specified customer number.

Retrieve all the social media users which has mapped to the specific customer.

Required scope: hybris.cecentercustomer_view

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

Manage addresses of a given customer for a given tenant.

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

post

Create an address for a given customer.

Required scope: hybris.cecentercustomer_manage

get

Retrieve a list of addresses of a given customer.

Required scope: hybris.cecentercustomer_view

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

Manage a single address of a given customer.

put

Update an address of a given customer.

Required scope: hybris.cecentercustomer_manage

delete

Delete an address.

Required scope: hybris.cecentercustomer_manage

/{tenant}/sdCustomerMappings

Manage customer deletion logs for a given tenant.

/{tenant}/sdCustomerMappings

post

Create a customer deletion log.

Required scope: hybris.cecentercustomer_manage

get

Retrieve a list of customer deletion logs.

Required scope: hybris.cecentercustomer_view

/{tenant}/sdCustomerMappings/{customerNumber}

Manage a deletion log for a given customer.

delete

Delete a customer deletion log.

Required scope: hybris.cecentercustomer_manage


Scopes

The table shows the scopes that the Engagement Center Customer service supports.

SCOPEDESCRIPTION
hybris.cecentercustomer_viewUse this scope to view Engagement Center customer information.
hybris.cecentercustomer_manageUse this scope to create or update Engagement Center customer information.

For more information about scopes, authorization, and authentication procedures for YaaS services, see Scopes and Authorization.


Store Customer Addresses

The customer address is an integral part of the customer data because it is embedded in the customer profile. Use these endpoints to manage customer addresses:

  • /{tenant}/customers/{customerNumber}/addresses: Use this resource to get all addresses for a specific account. You can also create a new address for any customer account.
  • /{tenant}/customers/{customerNumber}/addresses/{addressId}: Use this resource to retrieve an address by providing the address ID in the URL as the {addressId} path parameter value. You can also update or delete an address.

For more information, see Storing Customer Addresses.


Extend Customer Information

A set of properties, such as contactEmail and customerNumber, define customers. These properties uniquely identify a customer for the external world.

However, these schema-based properties are few and common to all customers. Mixins can help you to define a set of additional properties to extend information about one customer. You can also reuse your customer mixins in many different customer definitions.

In the Engagement Center Customer service, these methods and endpoints support customer mixins:

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

For more information, see Extend Customer Information.


Social Media User

Social media user refers to a user harvested from social media channels such as Facebook, Twitter, SAP Jam Communities, and so on. Use the Social Media User service to create a social media user in the Social Media User service and map it to an existing customer account. For more information, see the Social Media User.

With the Engagement Center Customer service, use the /{tenant}/customers/{customerNumber}/socialMediaUsers endpoint to retrieve all social media users mapped to the specified customer account.


Create a New Customer

This tutorial shows how a merchant can create a new customer profile using a POST request.

Request

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_manage.
  • URI Parameters
    • {tenant}: The name of the current tenant
  • Body: The body can contain some basic customer data.

Example

{
  "firstName": "Arnold",
  "contactEmail": "noreply@hybristest.com",
  "company": "hybris",
  "preferredLanguage": "en_UK",
  "preferredCurrency": "GBP"
}

Validation

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

  • If you try to create an account using a contactEmail value that already exists, the service returns the error, “The request failed because there was a conflict with another resource.â€�
  • If validation fails, the service returns the error code 409.

Response

A successful response returns a 201 status code. The JSON response content looks similar to the example shown.

Example

{
  "id": "C1517747615", 
  "link": https://api.beta.yaas.io/hybris/cecentercustomer/v1/cecenterprodman/customers/C1517747615
  }


Create a Customer without an Email Address

This tutorial describes how to use a POST request to create a customer account without an associated email address.

Request

To create a customer profile without an email, make this request:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers

For more information, see Create Customer without Email.


Update a Customer Profile

Merchants can update customer profile data using a PUT request. You can modify any customer property except for customerNumber. To update a customer profile, make this request:

  • Method: PUT
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/customers/{customerNumber}

For more information, see Update Customer Profile.


Get all Customer Accounts

Merchants with the proper scope can view all customer accounts in a specified tenant. To get all customer accounts, make this request:

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

The response contains the hybris-Count header with the total number of results of this type.

For more information, see Get All Customer Accounts.


Get a Specific Customer Account

Merchants can retrieve the details of any customer account for a particular tenant. The request body does not need to contain any information. The request sends all necessary data, together with the query parameter and message headers. To get a customer account, use the request:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers/{customerNumber}

For more information, see Get Specific Customer Account.


Use Query Parameters

You can use several query parameters to influence the way your results display. You can control the sort order and the number of results displayed per page. You can also apply filters based on the selected attributes. For more information, see Use Query Parameters.


Add an Internal Account to a Customer Profile

It is possible for a customer profile to exist without an internal account assigned. This can happen, for example, if a customer is 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 in the Scopes topic of the Engagement Center Customer service documentation.

To add an internal account, use the request:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers/CO139024732/accounts/internal

For more information, see Add Internal Account to Customer.


Create a Customer with Mixins

This tutorial describes how merchants can create a customer profile using customer mixins.

Request

To create a customer profile with mixins, use this request:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_manage.
  • URI Parameters
    • {tenant}: The name of the current tenant
  • Body: The body can contain some basic customer data and the mixins attribute is required in this scenario.

Example

{
  "metadata": {
    "mixins": {
      "additionalCode": "https://api.beta.yaas.io/hybris/schema/v1/kiwistest/example-schema.json"
    }
  },
  "mixins": {
    "additionalCode": {
      "code": "DFG-334-98330-X"
    }
  },
  "firstName": "Arnold",
  "contactEmail": "noreply@yaastest.com",
  "company": "hybris",
  "preferredLanguage": "en_UK",
  "preferredCurrency": "GBP",
  "preferredSite": "UK_site",
  "active": true
}

Response

A successful response returns a 201 status code. The JSON response content looks similar to the example shown.

Example

{
  "id": " C6726280624", 
  "link": https://api.beta.yaas.io/hybris/cecentercustomer/v1/cecenterprodman/customers/C6726280624
}


Retrieve a Customer Profile with Mixins

This tutorial describes how merchants can retrieve a customer profile with customer mixins.

Request

To retrieve a customer profile with mixins, use this request:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers/{customerNumber}
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_view.
  • URI Parameters
    • {tenant}: The name of the current tenant
  • Query Parameters:
    • expand: Set this parameter to mixin:{*} or mixin:{mixin name}.

Response

A successful response returns a 200 status code. The JSON response content looks similar to the example shown.

Example

{
  "customerNumber": "C6726280624",
  "firstName": "lilu00",
  "contactEmail": "001noreply@yaastest.com",
  "company": "hybris",
  "preferredLanguage": "en_UK",
  "preferredCurrency": "GBP",
  "metadata": {
    "mixins": {
     "additionalCode": "https://api.beta.yaas.io/hybris/schema/v1/kiwistest/example-schema.json"
    }
  },
  "mixins": {
    "additionalCode": {
      "code": "DFG-334-98330-X"
    }
  }
}


Retrieve Social Media Users

This tutorial describes how merchants can retrieve all of the social media users mapped to a customer account.

Request

To retrieve social media users, make this request:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers/{customerNumber}/socialMediaUsers
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_view.
  • URI Parameters
    • {tenant}: The name of the current tenant
    • {customerNumber}: The customer number to retrieve

Response

A successful response returns a 200 status code. The JSON response content looks similar to the example shown.

Example

[
  {
    "communicationMediumID": "SAP_COMMUNITY",
    "consentGivenBy": "John Marker",
    "consentGivenOn": "2015-12-02T14:10:00.000+0000",
    "creationDateTime": "2015-10-02T14:10:00.000+0000",
    "firstName": "Mary",
    "fullName": "Mary Smith",
    "id": "570f6adaf5563e001d56de87",
    "lastName": "Smith",
    "provider": "John Marker",
    "referenceCustomerNumber": "C8020362178",
    "socialMediaEmail": "mary.smith@hybristest.com",
    "socialMediaUserAccountName": "Mary",
    "socialMediaUserID": "579849303",
    "socialMediaUserProfilePhotoLink": "www.test.com"
  },
  {
    "communicationMediumID": "SAP_COMMUNITY",
    "consentGivenBy": "xiao.zhao@sap.com",
    "consentGivenOn": "2016-04-11T07:37:47.394+0000",
    "creationDateTime": "2015-11-20T05:17:20.000+0000",
    "firstName": "kang",
    "fullName": "kang chengkun",
    "id": "570600520941f5001dde7365",
    "lastName": "chengkun",
    "provider": "twitter",
    "referenceCustomerNumber": "C8020362178",
    "socialMediaEmail": "kangwen6663@126.com",
    "socialMediaUserAccountName": "conrad",
    "socialMediaUserID": "ZTbG506cJJFyLjWK6k6bxh",
    "socialMediaUserProfilePhotoLink": "https://acecorp2.community-demo.sapjam.com/uploads/production/registered_user/profile_photo/ZTbG506cJJFyLjWK6k6bxh/thumb48x48_-5_16_Kang_Chengkun.jpg"
  }
]


Delete a Customer Profile

The Engagement Center Customer service allows merchants to delete customer profiles and associated accounts. This tutorial describes how to delete customer profiles and accounts using a DELETE request

Request

To delete a customer profile, send a DELETE request to the /{tenant}/cecentercustomers/{customerNumber} endpoint.

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/customers/{customerNumber}
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_manage.
  • URI Parameters
    • {tenant}: The name of the current tenant
    • {customerNumber}: The customer number to delete

Response

A successful response returns a 202 status code.

For more information, see Delete a Customer Profile As Merchant.


Create a SD Customer Mapping

You can create a customer mapping between a customer number and an ERP SD customer number.

Request

To create an SD customer mapping, you need:

  • Method: POST
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/sdCustomerMappings
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_manage.
  • URI Parameters
    • {tenant}: The name of the current tenant
  • Body: The body can contain the mapping entry between the account ID and SD customer number.

Example

{
  "customerNumber": "C010101001",
  "sdCustomerNumber": "0003144965",
  "deletedInYaaS": false
}

Response

A successful response returns a 201 status code. The JSON response content looks similar to the example shown.

Example

{
  "id": "587453d08b7ee0001da9625f",
  "link": "https://api.beta.yaas.io/hybris/dcecentercustomer/v1/cecenterdevman/sdCustomerMappings/587453d08b7ee0001da9625f"
}


Retrieve SD Customer Mapping

You can retrieve a list of mappings between customer numbers and ERP SD customer numbers.

Request

To retrieve a list of SD customer mappings, you need:

  • Method: GET
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/sdCustomerMappings
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_view.
  • URI Parameters
    • {tenant}: The name of the current tenant
  • Query Parameters:
    • pageSize: 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: The page number to retrieve. Page numbering starts with one.
    • q: A simple query criteria based on available fields to limit returned results.

Response

A successful response returns a 200 status code. The JSON response content looks similar to the example shown.

Example

[
  {
    "customerNumber": "C7534120357",
    "deletedInYaaS": false,
    "sdCustomerNumber": "0000100080"
  },
  {
    "customerNumber": "C010101001",
    "deletedInYaaS": false,
    "sdCustomerNumber": "0003144965"
  },
  {
    "customerNumber": "C010101001",
    "deletedInYaaS": false,
    "sdCustomerNumber": "0003144965"
  }
]


Delete an SD Customer Mapping

You can delete an SD customer mapping.

Request

To delete an SD customer mapping, you need:

  • Method: DELETE
  • Request URL: https://api.beta.yaas.io/hybris/cecentercustomer/v1/{tenant}/sdCustomerMappings/{customerNumber}
  • Headers
    • Authorization: This requires a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.cecentercustomer_manage.
  • URI Parameters
    • {tenant}: The name of the current tenant
    • {customerNumber}: The customer number for which to delete the mapping

Response

A successful response returns a 204 status code.


Error Types

For information about error codes, see the API Reference.


Glossary

TermDescription
customer 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.


  • 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.