Customer Service (customer-managed)

Download OpenAPI specification:Download

Create, manage, and delete customer profiles.

Note: This part of the Customer Service is managed by the customers on the storefront.


Key Features:

  • Rich customer profiles that are extensible with custom fields
  • Multiple addresses for payment and delivery
  • Social login with Twitter, Facebook, and others

Key Benefits:

  • Self-service for customers to manage profile information
  • Convenient login and removal of login barriers with SSO for social logins
  • Capture data that is important for your business to serve your customers better
  • Secure login for your customers to their profile

Addresses

Adding a customer address

Adds an address to a customer's profile.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
contactName
string
companyName
string
street
string
streetNumber
string
streetAppendix
string
extraLine1
string
extraLine2
string
extraLine3
string
extraLine4
string
zipCode
string
city
string
country
string
state
string
contactPhone
string
tags
Array of strings
object (DefaultDtoMetadata)

Links to mixin schemas.

mixins
object

Customer address' additional properties.

Responses
201

Created

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

post/{tenant}/me/addresses
Request samples
application/json
{
  • "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": [
    ]
}
Response samples
application/json
{
  • "id": "b05c20e034"
}

Retrieving a customer's addresses

Retrieves a list of addresses for a customer.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

get/{tenant}/me/addresses
Request samples
Response samples
application/json
[
  • {
    }
]

Updating a customer's address

Updates a specified customer address.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
addressId
required
string non-empty

Address' unique identifier generated when the address is added to a customer's profile.

tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
contactName
string
companyName
string
street
string
streetNumber
string
streetAppendix
string
extraLine1
string
extraLine2
string
extraLine3
string
extraLine4
string
zipCode
string
city
string
country
string
state
string
contactPhone
string
tags
Array of strings
object (DefaultDtoMetadata)

Links to mixin schemas.

mixins
object

Customer address' additional properties.

isDefault
boolean

Flag indicating whether the address is the customer's default address.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Address with the specified addressId doesn't exist.

patch/{tenant}/me/addresses/{addressId}
Request samples
application/json
{
  • "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": [
    ],
  • "isDefault": true
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Retrieving a customer's address

Retrieves a specified customer address and its details.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
addressId
required
string non-empty

Address' unique identifier generated when the address is added to a customer's profile.

tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Address with the specified addressId doesn't exist.

get/{tenant}/me/addresses/{addressId}
Request samples
Response samples
application/json
{
  • "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": [
    ],
  • "id": "b05c20e034",
  • "isDefault": true
}

Deleting a customer's address

Deletes a specified customer address and accounts associated with it.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
addressId
required
string non-empty

Address' unique identifier generated when the address is added to a customer's profile.

tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Address with the specified addressId doesn't exist.

delete/{tenant}/me/addresses/{addressId}
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Adding tags to a customer's address

Adds tags to a specified customer address.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

addressId
required
string non-empty

Address' unique identifier generated when the address is added to a customer's profile.

query Parameters
tags
required
string non-empty

List of address tags, separated by commas.

Example: tags=BILLING,SHIPPING
Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Address with the specified addressId doesn't exist.

post/{tenant}/me/addresses/{addressId}/tags
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Deleting tags from a customer's address

Deletes tags from a specified customer address.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

addressId
required
string non-empty

Address' unique identifier generated when the address is added to a customer's profile.

query Parameters
tags
required
string non-empty

List of address tags, separated by commas.

Example: tags=BILLING,SHIPPING
Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Address with the specified addressId doesn't exist.

delete/{tenant}/me/addresses/{addressId}/tags
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Account and profile

Updating a customer's profile

Updates a customer's profile.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema:
title
string
firstName
string
middleName
string
lastName
string
contactPhone
string
company
string
preferredLanguage
string
Default: "en_US"

Customer's preferred language.

preferredCurrency
string = 3 characters
Default: "USD"

Customer's preferred currency, compliant with the ISO 4217 standard.

preferredSite
string
Default: "main"

Customer's preferred site.

object (B2bProperties)

Additional properties for B2B customer. If property is provided, additional validation for address and customer details is executing.

object (DefaultDtoMetadata)

Links to mixin schemas.

mixins
object

Customer account's additional properties.

contactEmail
string
Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

patch/{tenant}/me
Request samples
{
  • "title": "MR",
  • "firstName": "John",
  • "lastName": "Doe",
  • "contactEmail": "example@customer.com",
  • "contactPhone": "123456789",
  • "company": "Emporix",
  • "preferredLanguage": "en_US",
  • "preferredCurrency": "EUR",
  • "preferredSite": "main",
  • "b2b": {
    },
  • "metadata": {
    }
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Retrieving a customer's profile

Retrieves a customer's profile.

Note: The request needs to be authorized with a customer's access token or an anonymous access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken or AnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
expand
string

List of additional attributes to be retrieved, separated by commas. Possible value to be passed in this parameter is addresses.

Example: expand=addresses
Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

get/{tenant}/me
Request samples
Response samples
application/json
{
  • "title": "MR",
  • "firstName": "John",
  • "lastName": "Doe",
  • "contactPhone": "123456789",
  • "company": "Emporix",
  • "preferredLanguage": "en_US",
  • "preferredCurrency": "USD",
  • "preferredSite": "default",
  • "metadata": {
    },
  • "mixins": { },
  • "customerNumber": "13869000",
  • "id": "13869000",
  • "accounts": [
    ],
  • "contactEmail": "example@customer.com",
  • "b2b": {
    }
}

Deleting a customer's profile

Deletes a customer's profile and the account associated with it.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
token
string

Token received by the customer through email.

Responses
202

Customer profile deletion confirmation was successfully accepted

204

Customer profile deletion request was successful

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

delete/{tenant}/me
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Assigning an account to a customer's profile

Assigns a customer account to the customer's profile.


Required scopes

  • customer.customer_update or customer.customer_manage
SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string
Request Body schema: application/json
email
required
string

Customer's email address.

password
required
string

Customer's account password.

Responses
201

Created

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409
post/{tenant}/me/accounts/internal
Request samples
application/json
{
  • "email": "john.doe@example.com",
  • "password": "password123"
}
Response samples
application/json
{
  • "id": "13869000"
}

Authentication and authorization

Creating a new customer

Creates a new customer account.

Note: The request needs to be authorized with an anonymous access token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
email
required
string non-empty

Customer's email address.

password
required
string non-empty

Customer's account password.

object (CustomerUpdateDto)
object (Address)

Customer's address information.

object (PasswordAuthentication)
Responses
201

Created

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409
post/{tenant}/signup
Request samples
application/json
{
  • "email": "example@customer.com",
  • "password": "password123",
  • "customerDetails": {
    },
  • "customerAddress": {
    }
}
Response samples
application/json
{
  • "id": "13730481"
}

Logging in a customer

Logs in a customer and sends an authentication request and retrieves a customer token.

Note: The request needs to be authorized with an anonymous access token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
email
required
string

Customer's email address.

password
required
string

Customer's account password.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

post/{tenant}/login
Request samples
application/json
{
  • "email": "example@customer.com",
  • "password": "password123"
}
Response samples
application/json
{
  • "accessToken": "aYR3Lu3rpsQ9ODhBIR83b3txTr5K",
  • "saasToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMzg2OTAwMCIsImV4cCI6MTY0MDQ0NDAzMn0.lvxFOeCOk-DWi3kqwJwR8eKal3ON2rr53e9I6Pha5rI",
  • "expiresIn": 2591999,
  • "refreshToken": "94tKQ2Tsvlf9dYbmyccA7X1Rqe54B6dH",
  • "refreshTokenExpiresIn": 86399
}

Logging out a customer

Logs out a customer and invalidates their customer token.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
accessToken
required
string

Customer's access token to be invalidated.

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

get/{tenant}/logout
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Logging in a customer with Auth0

Logs in a customer using an authentication code from Auth0 and retrieves a standard customer token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

header Parameters
session-id
required
string

Anonymous customer's unique session identifier.

Request Body schema: application/json
email
string

Customer's email address.

name
string

Customer's name.

picture
string
provider
string

Identity provider.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

post/{tenant}/socialLogin
Request samples
application/json
{
  • "email": "example@customer.com",
  • "name": "John Doe",
  • "provider": "string"
}
Response samples
application/json
{
  • "customerNumber": "string"
}

Double opt-in

Creating a customer account with double opt-in

Creates a customer account using the token obtained through double opt-in.

Note: The request needs to be authorized with an anonymous access token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

token
required
string

The token sent in email to customer during account creation.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

get/{tenant}/signup/optin/{token}
Request samples
Response samples
application/json
{
  • "accessToken": "HzcnecB5l6STzXhRqU0Zp6hxS0Ay",
  • "saasToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI4NzQxMzI1MCIsImV4cCI6MTYzMjA1NDEzN30.p6g_G5ZbhjlvnObVC2OWGslLWWktxBw8onionfFvm4c",
  • "expiresIn": 2591999,
  • "refreshToken": "tMhLYc8pfAqb1g10Z1o7BxABArxXe3db",
  • "refreshTokenExpiresIn": 86399
}

Resending an account activation link to a customer

Resends an account activation link to the customer.

Note: The request needs to be authorized with an anonymous access token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
email
required
string

Customer's email address.

Responses
202

Accepted

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

post/{tenant}/signup/optin/refresh_token
Request samples
application/json
{
  • "email": "example@customer.com"
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Credentials

Sending a request to update a customer's email address

Sends a request to change a customer's email address. As a result, the customer receives a unique token through email.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

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

Requires scope customer.customerprofile_edit

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
email
string

Customer's email address currently used for logging in.

password
string

Customer's account password.

newEmail
string

Customer's new email address.

syncContactEmail
boolean
Default: false

Flag indicating whether the contactEmail should be changed to the new email address.

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

post/{tenant}/me/accounts/internal/email/change
Request samples
application/json
{
  • "email": "example@customer.com",
  • "password": "password123",
  • "newEmail": "example@emporix.com",
  • "syncContactEmail": true
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Updating a customer's email address

Updates a customer's email address using the token received through email.

Note: The request needs to be authorized with a anonymous access token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string

The tenant string is the project's Identifier from the Builder.

Request Body schema: application/json
token
string

Token received by the customer through email.

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

post/{tenant}/me/accounts/internal/email/change/confirm
Request samples
application/json
{
  • "token": "beExUmshJC5gnuXk1kET5dCLyQWkrAfKRGFOxVXLcJI13R1fn5USjaWku5G71whM"
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Sending a request to reset a customer's password

Sends a request to reset a Customer's account password. As a result, the customer receives a unique token through email.

Note: The request needs to be authorized with a anonymous access token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
email
required
string

Customer's email address.

site
string

Site from which password reset request was sent

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

post/{tenant}/password/reset
Request samples
application/json
{
  • "email": "example@customer.com"
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Resetting a customer's password

Resets a customer's password using the token received through email and sets a new password.

Note: The request needs to be authorized with a anonymous access token.


Required scopes

No specific scopes are required.

SecurityAnonymousAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
token
required
string

Token received by the customer through email.

password
required
string

Customer's new account password.

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

post/{tenant}/password/reset/update
Request samples
application/json
{
  • "token": "beExUmshJC5gnuXk1kET5dCLyQWkrAfKRGFOxVXLcJI13R1fn5USjaWku5G71whM",
  • "password": "P@ssw0rd123"
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Changing a customer's password

Changes a Customer's account password.

Note: The request needs to be authorized with a customer's access token.


Required scopes

No specific scopes are required.

SecurityCustomerAccessToken
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
currentPassword
required
string

Customer's current account password.

newPassword
required
string

Customer's new account password.

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

post/{tenant}/password/change
Request samples
application/json
{
  • "currentPassword": "password123",
  • "newPassword": "P@ssw0rd123"
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}