Customer Management Tutorial
Last updated
Was this helpful?
Last updated
Was this helpful?
Take a look at the relationships between objects in the Customer Management Service and other resources in the Emporix Commerce Engine. Click the diagram to enlarge it:
Setting up a business customer's information is a process made up of two steps:
Make sure you have marked the country in which the company operates as active. You can do it by sending a request to the Updating a country endpoint in the Emporix API Country Service.
A location is a physical address where a company operates, such as its headquarters, office, or warehouse. To add a new location, you need to send a request to the Creating a new location endpoint.
curl -i -X POST \
'https://api.emporix.io/customer-management/{tenant}/locations' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Main HQ",
"type": "HEADQUARTER",
"contactDetails": {
"emails": [
"jon.doe@example.com",
"adam.smith@sample.org"
],
"phones": [
"1234567890",
"123456789"
],
"addressLine1": "W Sample St",
"addressLine2": "3601-3799",
"city": "South Bend",
"state": "Indiana",
"postcode": "46619",
"countryCode": "US",
"tags": [
"shipping"
]
}
}'The id from the response is further referred to as locationId.
A legal entity is a representation of a company. To add a new legal entity, you need to send a request to the Creating a new legal entity endpoint and provide the locationId in the request body.
curl -i -X POST \
'https://api.emporix.io/customer-management/{tenant}/legal-entities' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Company name",
"type": "COMPANY",
"legalInfo": {
"legalName": "Some company name",
"registrationDate": "2022-03-31T13:18:02.379Z",
"registrationAgency": "Comp reg agency",
"registrationId": "627e06ecf0452c2d6c0b81391",
"countryOfRegistration": "DE",
"taxRegistrationNumber": "1234"
},
"accountLimit": {
"currency": "EUR",
"value": 1000.99
},
"customerGroups": [
{
"id": "123e06ecf0452c2d6c0b81390",
"name": {
"en": "En customer group name",
"de": "De customer group name"
}
}
],
"entitiesAddresses": [
{
"id": "123e123455452c2d6c0b81390"
},
{
"id": "123e06ecf0acd223140b12345"
}
],
"approvalGroup": [
{
"id": "123e121111452c12330b81390"
},
{
"id": "123e061110acd223133333345"
}
]
}'Subsidiaries are companies legally owned or controlled by other companies. In the Emporix Commerce Engine, subsidiaries are structured the same way as regular companies — the only difference is that a subsidiary must have its parent company specified.
Make sure you have already finished the How to set up business customer information tutorial.
To find out what a company's ID is, you need to send a request to the Retrieving all legal entities endpoint and use the q query parameter to find the desired company.
curl -i -X GET \
'https://api.emporix.io/customer-management/{tenant}/legal-entities?pageNumber=1&pageSize=16&sort=name%2Cmetadata.createdAt%3Adesc&q=name%3A~john&fields=name%2Ctype&id=string&name=string&type=COMPANY&parentId=string&legalInfo.legalName=string&legalInfo.registrationDate=string&legalInfo.taxRegistrationNumber=string&legalInfo.registrationAgency=string&legalInfo.countryOfRegistration=string&legalInfo.registrationId=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'X-Total-Count: false'The id from the response is further referred to as parentId.
Subsidiaries are added similarly to their parent companies. To add a new subsidiary, send a request to the Creating a new legal entity endpoint. In the request body, set the type field to SUBSIDIARY and provide the parentId.
curl -i -X POST \
'https://api.emporix.io/customer-management/{tenant}/legal-entities' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Company name",
"type": "COMPANY",
"legalInfo": {
"legalName": "Some company name",
"registrationDate": "2022-03-31T13:18:02.379Z",
"registrationAgency": "Comp reg agency",
"registrationId": "627e06ecf0452c2d6c0b81391",
"countryOfRegistration": "DE",
"taxRegistrationNumber": "1234"
},
"accountLimit": {
"currency": "EUR",
"value": 1000.99
},
"customerGroups": [
{
"id": "123e06ecf0452c2d6c0b81390",
"name": {
"en": "En customer group name",
"de": "De customer group name"
}
}
],
"entitiesAddresses": [
{
"id": "123e123455452c2d6c0b81390"
},
{
"id": "123e06ecf0acd223140b12345"
}
],
"approvalGroup": [
{
"id": "123e121111452c12330b81390"
},
{
"id": "123e061110acd223133333345"
}
]
}'You can offer personalized pricing to your business customers' employees by adding them to company customer groups. A company customer group is automatically created when that company's data is added to the system.
When added to a subsidiary’s customer group, the employee is also automatically assigned to customer groups of all the subsidiary’s parent companies.
Make sure the following requirements are fulfilled:
You have already finished the How to set up business customer information tutorial.
The employee has their customer account set up.
A customer account can be created by the employee themselves or from your Emporix tenant's side. For more information, check out the following endpoints in the Emporix API Reference:
To find out what a company's ID is, you need to send a request to the Retrieving all legal entities endpoint and use the q query parameter to find the desired company.
curl -i -X GET \
'https://api.emporix.io/customer-management/{tenant}/legal-entities?pageNumber=1&pageSize=16&sort=name%2Cmetadata.createdAt%3Adesc&q=name%3A~john&fields=name%2Ctype&id=string&name=string&type=COMPANY&parentId=string&legalInfo.legalName=string&legalInfo.registrationDate=string&legalInfo.taxRegistrationNumber=string&legalInfo.registrationAgency=string&legalInfo.countryOfRegistration=string&legalInfo.registrationId=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'X-Total-Count: false'The id from the response is further referred to as legalEntityId.
To retrieve an employee's customer ID, you need to send a request to the Retrieving a list of customers endpoint and use the q query parameter. For example, you can search for a customer with a specific email address with q=contactEmail:employeeEmail.
curl -i -X GET \
'https://api.emporix.io/customer/{tenant}/customers?q=contactEmail%3A{email}&sort=string&pageNumber=1&pageSize=60&expand=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'The id from the response is further referred to as customerId.
A contact represents an employee of one or more business customers.
To assign a contact to a legal entity (in this case, the desired company), you need to send a request to the Creating a new contact assignment endpoint and provide legalEntityId and customerId in the request body.
curl -i -X POST \
'https://api.emporix.io/customer-management/{tenant}/contact-assignments' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"legalEntity": {
"id": "612306ecf0452c2d6c0b81392"
},
"customer": {
"id": "612306ecf0452c2d6c0b81123"
},
"type": "BILLING",
"primary": true
}'Once desired employees are added to appropriate customer groups, you can — for example — create personalized price lists for them. For instructions, check out How to configure a price list in the Price Service guide.
To test the endpoint, open the API reference below or check the example of a curl request.
To test the endpoint, open the API reference below or check the example of a curl request.
To test the endpoint, open the API reference below or check the example of a curl request.
To test the endpoint, open the API reference below or check the example of a curl request.
To test the endpoint, open the API reference below or check the example of a curl request.
To test the endpoint, open the API reference below or check the example of a curl request.
To test the endpoint, open the API reference below or check the example of a curl request.
