Customer Management (Customer Managed) Tutorial

The Customer Service (Customer Managed) allows you to create, manage, and delete customer profiles from your commerce frontend perspective. You might use the Customer Service endpoints when implementing your custom commerce storefront or testing out your flows. It enables you to generate relevant access tokens to log in anonymous or registered customers on the storefront.

This tutorial guides you through the process of managing customer authentication, including creating customer accounts, logging in customers, and managing authentication tokens.

How to manage customer authentication

Customer authentication is a fundamental part of the customer experience. This section covers the complete authentication flow, from requesting anonymous tokens for browsing to logging in registered customers and managing their sessions.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

1

Requesting an anonymous token

When a user enters your storefront, before they choose to log in, an anonymous user session is created. An anonymous token allows customers to browse products, view prices, and add products to the cart without being logged in.

Get an anonymous access token by sending a request to the Requesting an anonymous token endpoint.

curl -i -X GET 
  'https://api.emporix.io/customerlogin/auth/anonymous/login?tenant={tenant}&client_id={client_id_storefront}'

Pass the Storefront Client ID in the request.

Sample response returns relevant access credentials:

{
  "token_type": "Bearer",
  "access_token": "tpYgJPZqddEQ2zwfzNtx79noBP65",
  "expires_in": 3599,
  "refresh_token": "7FnviYrxvQWYdzUVBVTvXeNAA4Jy1HPe",
  "refresh_token_expires_in": 86399,
  "sessionId": "6d4d4d5e-04b9-40c5-9074-4df1405c6081",
  "scope": "tenant={tenant}"
}

The anonymous token is valid for one hour. After that time, it should be refreshed to keep the same session ID associated.

2

Refreshing an anonymous token

When the anonymous token is about to expire, use the refresh mechanism to maintain the same customer's session ID and allow them browsing without interruption.

Send a request to the Refreshing an anonymous token endpoint.

curl -i -X GET \
  'https://api.emporix.io/customerlogin/auth/anonymous/refresh?tenant={tenant}&refresh_token={refresh_token}&client_id={client_id_storefront}'

See the sample response:

{
  "token_type": "Bearer",
  "access_token": "tpYgJPZqddEQ2zwfzNtx79noBP65",
  "expires_in": 3599,
  "refresh_token": "7FnviYrxvQWYdzUVBVTvXeNAA4Jy1HPe",
  "refresh_token_expires_in": 86399,
  "sessionId": "6d4d4d5e-04b9-40c5-9074-4df1405c6081",
  "scope": "tenant={tenant}"
}

It's recommended to use the refresh_token parameter instead of the deprecated anonymous_token parameter. The refresh token is valid for 24 hours (86399 seconds).

3

Creating a new customer

To create a new customer account, send a request to the Creating a new customer endpoint. Authorize the request with the anonymous access token.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/signup' 
  -H 'Authorization: Bearer {anonymous_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "email": "[email protected]",
    "password": "password123",
    "customerDetails": {
      "title": "MR",
      "firstName": "John",
      "middleName": "",
      "lastName": "Doe",
      "contactEmail": "[email protected]",
      "contactPhone": "123456789",
      "company": "Emporix",
      "preferredLanguage": "en_US",
      "preferredCurrency": "EUR",
      "preferredSite": "main",
      "b2b": {
        "companyRegistrationId": "123-456-789",
        "legalEntities": [
          {
            "id": "67e162a3ad4e2f12bc4f9306",
            "name": "ABC",
            "contactAssignmentId": "91033918"
          }
        ]
      }
    },
    "customerAddress": {
      "contactName": "John Doe",
      "companyName": "Emporix",
      "street": "Platz der Republik",
      "streetNumber": "1",
      "streetAppendix": "",
      "extraLine1": "",
      "extraLine2": "",
      "zipCode": "11011",
      "city": "Berlin",
      "country": "DE",
      "state": "Berlin",
      "contactPhone": "123456789",
      "tags": ["BILLING", "SHIPPING"]
    }
  }'

The response returns the ID of the created customer.

If you want to use separate sign-up credentials (different email for login than the main contact email), you can include the signup object with email and password fields in the request.

4

Activating customer account as an employee

The created customer's account is inactive and requires an action on the employee's side to enable and activate the account. To achieve this, you need the relevant employee access token.

To obtain the employee token, see the steps described in the Customer Service (Tenant Managed) Tutorial.

Send the PATCH request for Updating a customer profile.

curl -X PATCH "https://api.emporix.io/customer/{tenant}/customers/{customerNumber}" 
  -H "Authorization: Bearer YOUR_OAUTH2_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "active": true,
    "onHold": false
  }'

As a result, the customer is able to continue with logging in to their account.

5

Logging in a customer

After creating and getting their account activated, customers can log in to the store using their email and password. This operation returns both a customer access token and a SaaS token.

Send an authorization request to the Logging in a customer endpoint, passing the anonymous access token as the authorization method.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/login' 
  -H 'Authorization: Bearer {anonymous_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "email": "[email protected]",
    "password": "password123"
  }'

The example response looks as follows:

{
  "access_token": "aYR3Lu3rpsQ9ODhBIR83b3txTr5K",
  "saas_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMzg2OTAwMCIsImV4cCI6MTY0MDQ0NDAzMn0.lvxFOeCOk-DWi3kqwJwR8eKal3ON2rr53e9I6Pha5rI",
  "expires_in": 2591999,
  "refresh_token": "94tKQ2Tsvlf9dYbmyccA7X1Rqe54B6dH",
  "refresh_token_expires_in": 86399,
  "token_type": "Bearer",
  "session_id": "45c9726e-77c8-4bd0-b29d-61ab56f59726",
  "initialPassword": false
}

The customer access token is valid for 30 days (2591999 seconds). The SaaS token is a JSON Web Token (JWT) containing encrypted customer data.

6

Refreshing a customer token

As the customer access tokens expire after 30 days, you need to introduce a mechanism to prolong the session. To maintain an active authenticated session without requiring the customer to log in again, refresh the customer token before it expires. Send a request to the Refreshing a customer token endpoint.

Authorize the request with the anonymous access token.

curl -i -X GET \
  'https://api.emporix.io/customer/{tenant}/refreshauthtoken?refreshToken={customer_refresh_token}&legalEntityId={legalEntityId}' \
  -H 'Authorization: Bearer {anonymous_access_token}'

The legalEntityId parameter is optional. Use it when you want to associate the session with a specific legal entity.

7

Validating a token

Token validation allows you to verify whether a token is still valid and retrieve information about the token, such as expiration time, scopes, and associated session details. Validate tokens before making authenticated requests to ensure the token hasn't expired or been revoked. This helps prevent authentication errors and allows you to proactively refresh tokens before they expire.

Send a request to the Validate a token endpoint.

Authorize the request with the customer access token.

curl -i -X GET \
  'https://api.emporix.io/customer/{tenant}/validateauthtoken' \
  -H 'Authorization: Bearer {customer_access_token}'

The response includes the details about the token type and granted scopes, for example:

{
  "token_type": "Bearer",
  "expires_in": 2591974,
  "scope": "approval.approval_read_own customermanagement.legalentity_read_own customer.customer_read_own quote.quote_read_own returns.returns_read_own iam.scope_read_own iam.user_read_own customersegment.segment_read_own iam.group_read_own order.order_readascustomer coupon.coupon_redeem customer.customerprofile_edit quote.quote_manage_own returns.returns_manage_own customer.customer_manage_own approval.approval_manage_own order.order_updateascustomer iam.assignment_delete_own customer.consent_view customer.customerprofile_view order.history_view iam.assignment_create_own customer.consent_manage tenant=test",
  "sessionId": "415c340b-5996-4112-bb3b-38139a409f93",
  "email": "[email protected]",
  "legalEntityId": "53ac81fd0cce8b26b36f3492"
}

If the token is invalid, the endpoint returns a 401 Unauthorized status code.

8

Logging in a customer using social login

Social login allows customers to authenticate using their existing social media accounts (for example, Google, Facebook) through Auth0. This provides a convenient login experience without requiring customers to create a new password. You can enable the social login option in your store by using a dedicated endpoint.

Send a request to the Logging in a customer with social login endpoint.

Authorize the request with the anonymous access token.

curl -i -X POST \
  'https://api.emporix.io/customer/{tenant}/socialLogin?code={authorization_code}&redirect_uri={redirect_uri}&code_verifier={code_verifier}' \
  -H 'Authorization: Bearer {anonymous_access_token}' \
  -H 'session-id: {session_id}'

The response returns the social access token to authenticate the customer.

{
  "social_access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "social_id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "94tKQ2Tsvlf9dYbmyccA7X1Rqe54B6dH",
  "refresh_token_expires_in": "86399",
  "session_idle_time": 3600,
  "token_type": "Bearer",
  "access_token": "aYR3Lu3rpsQ9ODhBIR83b3txTr5K",
  "saas_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMzg2OTAwMCIsImV4cCI6MTY0MDQ0NDAzMn0.lvxFOeCOk-DWi3kqwJwR8eKal3ON2rr53e9I6Pha5rI",
  "expires_in": "2591999",
  "scope": "tenant={tenant}"
}

The code_verifier parameter is required only if using PKCE (Proof Key for Code Exchange) flow. The session-id header is optional - use it to maintain the same session when transitioning from anonymous to authenticated state.

9

Logging out the customer

When a customer wants to end their session, log them out to invalidate their customer access token. This ensures that the token cannot be used for further authenticated requests.

Send a request to the Logging out a customer endpoint.

Authorize the request with a customer access token.

curl -i -X GET \
  'https://api.emporix.io/customer/{tenant}/logout?accessToken={customer_access_token}' \
  -H 'Authorization: Bearer {customer_access_token}'

After logging out, the customer access token is invalidated and cannot be used for further requests. The customer needs to log in again to obtain a new token.

How to manage a customer's profile

Once a customer is logged in, they can manage their profile information, including personal details, addresses, and account settings. This section covers all the operations available for managing customer profiles.

1

Retrieving a customer profile

To allow a customer to check and modify the details associated with their account, fetch the current customer's profile information. Send a request to the Retrieving a customer profile endpoint.

Authorize the request with a customer access token or an anonymous access token, depending on the specific use case.

curl -i -X GET 
  'https://api.emporix.io/customer/{tenant}/me?expand=addresses,mixin:*' 
  -H 'Authorization: Bearer {customer_access_token}'

The response includes customer details such as personal information, preferred settings, and associated accounts:

{
  "title": "MR",
  "firstName": "John",
  "lastName": "Doe",
  "contactPhone": "123456789",
  "company": "Emporix",
  "preferredLanguage": "en_US",
  "preferredCurrency": "USD",
  "preferredSite": "default",
  "metadata": {
    "mixins": {},
    "version": 2
  },
  "mixins": {},
  "customerNumber": "13869000",
  "id": "13869000",
  "accounts": [
    {
      "id": "[email protected]"
    }
  ],
  "contactEmail": "[email protected]",
  "businessModel": "B2B",
  "b2b": {
    "companyRegistrationId": "123-456-789",
    "legalEntities": [
      {
        "id": "D165356",
        "name": "Emporix",
        "contactAssignmentId": "D436432"
      }
    ]
  }
}

Use the expand query parameter to include additional attributes like addresses or mixin:* to expand mixin schemas.

2

Updating a customer profile

Customers can update their personal details, preference settings, and B2B information. Send a request to the Updating a customer profile endpoint.

Authorize the request with a customer access token.

curl -i -X PATCH 
  'https://api.emporix.io/customer/{tenant}/me' 
  -H 'Authorization: Bearer {customer_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "title": "MR",
    "firstName": "John",
    "lastName": "Doe",
    "contactEmail": "[email protected]",
    "contactPhone": "123456789",
    "company": "Emporix",
    "preferredLanguage": "en_US",
    "preferredCurrency": "EUR",
    "preferredSite": "DE",
    "b2b": {
      "companyRegistrationId": "123-456-789"
    },
    "metadata": {
      "version": 1
    }
  }'

You can also use application/merge-patch+json as the Content-Type header for partial updates.

3

Adding an address to a customer profile

Customers can add shipping or billing addresses to their profile. Send a request to the Adding a customer address endpoint.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/me/addresses' 
  -H 'Authorization: Bearer {customer_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "contactName": "John Doe",
    "companyName": "Emporix",
    "street": "Platz der Republik",
    "streetNumber": "1",
    "streetAppendix": "",
    "extraLine1": "",
    "extraLine2": "",
    "extraLine3": "",
    "extraLine4": "",
    "zipCode": "11011",
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "contactPhone": "123456789",
    "tags": ["BILLING", "SHIPPING"]
  }'

The response returns the ID of the created address:

{
  "id": "b05c20e034"
}

Use the tags array to specify address types. Common values are BILLING and SHIPPING, but you can add your own.

4

Retrieving customer addresses

To retrieve all addresses associated with a customer profile, send a request to the Retrieving customer addresses endpoint.

curl -i -X GET 
  'https://api.emporix.io/customer/{tenant}/me/addresses' 
  -H 'Authorization: Bearer {customer_access_token}'

The response returns an array of addresses:

[
  {
    "contactName": "John Doe",
    "companyName": "Emporix",
    "street": "Platz der Republik",
    "streetNumber": "1",
    "streetAppendix": "",
    "extraLine1": "",
    "extraLine2": "",
    "extraLine3": "",
    "extraLine4": "",
    "zipCode": "11011",
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "contactPhone": "123456789",
    "tags": ["BILLING", "SHIPPING"],
    "id": "b05c20e034",
    "isDefault": true
  }
]

5

Retrieving a specific customer address

To retrieve details of a specific address, send a request to the Retrieving a customer address endpoint.

Authorize the request with a customer access token.

curl -i -X GET 
  'https://api.emporix.io/customer/{tenant}/me/addresses/{addressId}' 
  -H 'Authorization: Bearer {customer_access_token}'

The response returns the address details:

{
  "contactName": "John Doe",
  "companyName": "Emporix",
  "street": "Platz der Republik",
  "streetNumber": "1",
  "streetAppendix": "",
  "extraLine1": "",
  "extraLine2": "",
  "extraLine3": "",
  "extraLine4": "",
  "zipCode": "11011",
  "city": "Berlin",
  "country": "DE",
  "state": "Berlin",
  "contactPhone": "123456789",
  "tags": ["BILLING", "SHIPPING"],
  "id": "b05c20e034",
  "isDefault": true
}

6

Updating a customer address

To update an existing address, send a request to the Updating a customer address endpoint.

curl -i -X PATCH 
  'https://api.emporix.io/customer/{tenant}/me/addresses/{addressId}' 
  -H 'Authorization: Bearer {customer_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "contactName": "John Doe",
    "companyName": "Emporix",
    "street": "Platz der Republik",
    "streetNumber": "2",
    "streetAppendix": "Platz",
    "extraLine1": "",
    "extraLine2": "",
    "extraLine3": "",
    "extraLine4": "",
    "zipCode": "11011",
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "contactPhone": "123456789",
    "tags": ["BILLING", "SHIPPING"],
    "isDefault": true
  }'

Set the isDefault to true to mark the address as the default address for the customer.

7

Adding tags to a customer address

To add tags to an existing address, send a request to the Adding tags to a customer address endpoint.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/me/addresses/{addressId}/tags?tags=BILLING,SHIPPING,CUSTOM' 
  -H 'Authorization: Bearer {customer_access_token}'

Provide tags as a comma-separated list in the tags query parameter.

8

Deleting a customer address

To remove an address from a customer profile, send a request to the Deleting a customer address endpoint.

curl -i -X DELETE 
  'https://api.emporix.io/customer/{tenant}/me/addresses/{addressId}' 
  -H 'Authorization: Bearer {customer_access_token}'

Deleting an address also removes any accounts associated with it.

9

Deleting a customer profile

To delete a customer profile and the associated account, send a request to the Deleting a customer profile endpoint. In the query parameter, you can pass the token that the customer receives by email to confirm deletion.

curl -i -X DELETE 
  'https://api.emporix.io/customer/{tenant}/me?token={confirmation_token}' 
  -H 'Authorization: Bearer {customer_access_token}'

Deleting a customer profile permanently removes the profile and all associated accounts. This action may return 202 Accepted if confirmation is required, or 204 No Content if deletion is immediate.

How to manage customer credentials

Customers may need to change their email address or reset their password. This section covers the complete flow for managing customer credentials, including password reset and email change processes.

Note that to properly handle customer notifications, you need to have a mailing service configured first. For more information see Customer Communication Integrations.

1

Requesting a password reset

When a customer forgets their password, they can request a password reset. This sends a unique token to their email address that they can use to set a new password.

Send a request to the Sending a request to reset a customer password endpoint.

Authorize the request with an anonymous access token.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/password/reset' 
  -H 'Authorization: Bearer {anonymous_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "email": "[email protected]",
    "site": "main"
  }'

The site parameter is optional and specifies the site from which the password reset request was sent.

2

Resetting a password using token

After the customer receives the password reset token by email, they can use it to set a new password. Send a request to the Resetting a customer password endpoint.

Authorize the request with the anonymous access token.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/password/reset/update' 
  -H 'Authorization: Bearer {anonymous_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "token": "beExUmshJC5gnuXk1kET5dCLyQWkrAfKRGFOxVXLcJI13R1fn5USjaWku5G71whM",
    "password": "P@ssw0rd123"
  }'

The token is sent to the customer's email address and is required to complete the password reset process.

3

Changing a password

When a customer is logged in and wants to change their password, they can do so by providing their current password and the new password. Send a request to the Changing a customer password endpoint.

Authorize the request with a customer access token.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/password/change' 
  -H 'Authorization: Bearer {customer_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "currentPassword": "password123",
    "newPassword": "P@ssw0rd123"
  }'

The customer must provide their current password to verify their identity before setting a new password.

4

Request an email change

Customers can request to change their email address. This sends a confirmation token to the new email address. Send a request to the Sending a request to update a customer email address endpoint.

Authorize the request with a customer access token.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/me/accounts/internal/email/change' 
  -H 'Authorization: Bearer {customer_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "email": "[email protected]",
    "password": "password123",
    "newEmail": "[email protected]",
    "syncContactEmail": true
  }'

Set syncContactEmail to true if you want the contactEmail field in the customer profile to be updated to match the new email address.

5

Confirming an email change

After the customer receives the confirmation token by email at their new email address, they can confirm the email change. Send a request to the Updating a customer email address endpoint.

Authorize the request with an anonymous access token.

curl -i -X POST 
  'https://api.emporix.io/customer/{tenant}/me/accounts/internal/email/change/confirm' 
  -H 'Authorization: Bearer {anonymous_access_token}' 
  -H 'Content-Type: application/json' 
  -d '{
    "token": "beExUmshJC5gnuXk1kET5dCLyQWkrAfKRGFOxVXLcJI13R1fn5USjaWku5G71whM"
  }'

The token is sent to the new email address and must be used to complete the email change process.