Customer Management
Last updatedIntroduction#
This documentation delves into the key queries and mutations associated with customer management in DTC API. This documentation equips you with the knowledge needed to create customer-centric functionalities including registration, login, forgotten password, or newsletter along with back in stock subscriptions.
Customer structure#
The CustomerFragment provides a comprehensive view of customer details within the system. It includes essential information about the customer's identity, contact details, order history, and associated attributes.
Utilize this fragment to retrieve a snapshot of a customer's profile on any queries and mutations related to the customer.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
fragment CustomerFragment on Customer {
id
email
firstName
lastName
cellPhoneNumber
phoneNumber
totalOrders
billingAddress {
...AddressFragment
}
birthdate
websiteUrl
gender
language {
name
code
}
newsletterSubscriptions {
isActive
createdAt
country {
name
code
}
}
attributes {
...AttributeFragment
}
wishlists {
id
name
isDefault
items {
...DisplayItemFragment
}
}
subscriptionContracts {
...SubscriptionContractFragment
}
orders {
...OrderFragment
}
}
Registration#
To register a new customer you need to use the registerCustomer mutation. It accepts various input parameters to create a customer profile, including personal details, contact information, consents, and custom attributes. It’s required to provide a billingAddress, password and loginOnSuccess, while other fields are optional.
You can also set attributes on customer providing attribute and element names along with value for dynamic attributes, or attribute name and id for mapped ones.
If loginOnSuccess is set to true - customer becomes logged in. If set to false, they remains as a guest.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
mutation {
registerCustomer(
input: {
password: "secret"
billingAddress: {
email: "example@centra.com"
firstName: "Daniel"
lastName: "Ford"
country: "SE"
}
gender: MALE
consents: []
customAttributes: {
dynamicAttributes: [
{
attributeTypeName: "health"
attributeElementKey: "diet"
attributeElementValue: "none"
}
]
mappedAttributes: [
{ attributeTypeName: "registration_source", attributeId: 3 }
]
}
loginOnSuccess: true
}
) {
loggedIn {
...CustomerFragment
}
userErrors {
message
path
}
}
}
Login / Logout#
Login
To authenticate a shopper use a login mutation by providing their email and password. Upon successful login, the mutation returns information about the logged-in customer, including details such as customer ID, email, name, and additional profile information.
Logging in will not reset the state of the selection, all its properties, like selected items, country, will remain.
1
2
3
4
5
6
7
8
9
10
11
12
mutation {
login(email: "example@centra.com", password: "secret") {
loggedIn {
...CustomerFragment
}
userErrors {
path
message
}
}
}
Logout
The logout mutation is used to end a shopper's session, initiating a logout action. Depending on the configuration of the "Retain session after logout" plugin setting, the session can either be retained or cleared.
1
2
3
4
5
6
7
8
9
10
mutation {
logout {
session {
...SessionFragment
}
selection {
...SelectionFragment
}
}
}
Update customer#
Customer’s information can be updated using updateCustomer mutation. This mutation provides the flexibility to update various aspects of the customer's profile, ensuring accurate and up-to-date information. It allows for changes to the password, consents, attributes, and address details.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
mutation {
updateCustomer(
input: {
password: "new_secret"
billingAddress: {
email: "example@centra.com"
firstName: "Daniel"
lastName: "Ford"
country: "DE"
}
gender: MALE
consents: []
customAttributes: {
dynamicAttributes: [
{
attributeTypeName: "health"
attributeElementKey: "diet"
attributeElementValue: "vegan"
}
]
mappedAttributes: [
{ attributeTypeName: "registration_source", attributeId: 3 }
]
}
}
) {
customer {
...CustomerFragment
}
userErrors {
message
path
}
}
}
Get customer#
To get an actual customer's data you can use a customer query. It is designed for logged-in customers only.
1
2
3
4
5
query {
customer {
...CustomerFragment
}
}
Forgotten password#
The reset password flow comprises three essential steps:
Request reset password email
If a shopper wants to reset their password - resetPasswordEmail mutation must be called with a customer email and FE reset password URL. This triggers a reset password email containing a link to a frontend page. The link includes the store frontend URL from a Frontend URL plugin setting, the URL from the mutation, and two query parameters:
-
Customer id.
-
A hash to protect reset password action.
1
2
3
4
5
6
7
8
9
10
11
mutation {
resetPasswordEmail(
email: "example@centra.com"
url: "customer/reset-password"
) {
userErrors {
message
path
}
}
}
Note: Auto-registered customers cannot initiate a password reset.
Verify reset password hashes
Upon opening the link provided in the email, the frontend needs to verify the link's validity and ensure that the reset password action was legitimately requested. Call the verifyResetPasswordHashes mutation, providing the id and i query parameters received in the URI. If the parameters are valid, the DTC API responds with valid: true, allowing the shopper to set a new password.
1
2
3
4
5
6
7
8
9
10
11
12
mutation {
verifyResetPasswordHashes(
i: "241279e9ca655ab039c49d0032ed13ce"
id: "125"
) {
valid
userErrors {
message
path
}
}
}
Reset password
Once a new password is entered, call the resetPassword mutation to finalize the password reset. Provide the new password and the id and i query parameters from the previous call. If the password reset is successful, the DTC API responds with changed: true, indicating that the new password has been assigned to the customer's profile.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
mutation {
resetPassword(
password: "new_secret"
confirmPassword: "new_secret"
id: "125"
i: "241279e9ca655ab039c49d0032ed13ce"
loginOnSuccess: false
) {
changed
userErrors {
message
path
}
}
}
Newsletter subscription#
To subscribe customers for email newsletter you can use subscribeToNewsletter mutation. If you provide country and language in additional information they can be used to control the newsletter language and to filter newsletter updates on products available in the customer's Market.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
mutation {
subscribeToNewsletter(
email: "example@centra.com"
additionalInfo: {
emailField: ""
countryCode: "SE"
languageCode: "en"
gender: MALE
}
) {
subscribed
userErrors {
path
message
}
}
}
There is an additional field called emailField, which is a honeypot field for spam bots or web crawlers. In your FE, next to the subscribe form, you should implement a field or a checkbox which is not visible to the visitor, but clearly is part of the form from the code perspective. Any value passed to this form element should be passed to that variable. It's a signal to Centra, as well as to external mailer systems, that this subscription was filled out by a bot, so it should be ignored. At the same time, the API behaviour looks the same to the user, so the bot will not get any information back letting it know it failed to subscribe.
To read more and see some examples, check out the Rule article about email honey pots.
Back in stock subscription#
To allow shoppers to subscribe to a product and receive notifications once the product is available, the backInStockSubscribe mutation can be utilized. This functionality supports Centra Back in Stock notifications. While for logged-in shoppers you don't need to provide an email (as it's already available), for others, it's essential to include this information. A successful subscription is indicated by the DTC API returning subscribed: true. This confirms that the shopper has been successfully subscribed for Back In Stock notifications.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mutation {
backInStockSubscribe(
input: {
email: "example@centra.com"
shipTo: { countryCode: "SE" }
item: "10-1"
languageCode: "en"
}
) {
subscribed
userErrors {
message
path
}
}
}