Queries and mutations for managing Customers in the platform.

Queries

Query Customers

QUERYcustomers
Arguments
where​
String​
sort​
Array of String​
limit​
Int​
offset​
Int​

Get Customer

QUERYcustomer
Arguments
emailToken​
String​

Queries a customer with specified email token

passwordToken​
String​

Queries a customer with specified password token

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Customer

Mutations

Create (sign up) Customer

MUTATIONcustomerSignUp

Creates a customer. If an anonymous cart is given then the cart is assigned to the created customer and the version number of the Cart will increase. If the id of an anonymous session is given, all carts and orders will be assigned to the created customer.

Arguments
draft​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Authenticate (sign in) Customer

MUTATIONcustomerSignIn

Retrieves the authenticated customer (a customer that matches the given email/password pair).

There may be carts and orders created before the sign in that should be assigned to the customer account. With the anonymousCartId, a single anonymous cart can be assigned. With the anonymousId, all orders and carts that have this anonymousId set will be assigned to the customer. If both anonymousCartId and anonymousId are given, the anonymous cart must have the anonymousId.
Additionally, there might also exist one or more active customer carts from an earlier session. On customer sign in there are several ways how to proceed with this cart and the cart referenced by the anonymousCartId.
  • If the customer does not have a cart yet, the anonymous cart becomes the customer's cart.

  • If the customer already has one or more carts, the content of the anonymous cart will be copied to the customer's active cart that has been modified most recently.

    In this case the CartState of the anonymous cart gets changed to Merged while the customer's cart remains the Active cart.
    If a LineItem in the anonymous cart matches an existing line item, or a CustomLineItem matches an existing custom line item in the customer's cart, the maximum quantity of both line items is used as the new quantity.
    ItemShippingDetails are copied from the item with the highest quantity.
    If itemShippingAddresses are different in the two carts, the resulting cart contains the addresses of both the customer cart and the anonymous cart.

    Note, that it is not possible to merge carts that differ in their currency (set during creation of the cart).

If a cart is is returned as part of the CustomerSignInResult, it has been recalculated (it will have up-to-date prices, taxes and discounts, and invalid line items have been removed).
Arguments
draft​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Change password of Customer

MUTATIONcustomerChangePassword
Arguments
id​
String​
version​
Long​
currentPassword​
String​
newPassword​
String​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Output:Customer

Create password reset token for Customer

MUTATIONcustomerCreatePasswordResetToken

The token value is used to reset the password of the customer with the given email. The token is valid for the time-to-live period (TTL).

Arguments
email​
String​
ttlMinutes​
Int​

The validity of the created token in minutes.

storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

invalidateOlderTokens​
Boolean​

Invalidate older, previously created tokens when a new token is created.

Default: false​

Reset password of Customer

MUTATIONcustomerResetPassword

The following workflow can be used to reset the customer’s password:

  1. Create a password reset token and send it embedded in a link to the customer.
  2. When the customer clicks on the link, you may optionally retrieve customer by password token.
  3. When the customer entered new password, use reset customer’s password to reset the password.
Arguments
version​
Long​
tokenValue​
String​
newPassword​
String​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Output:Customer

Create email verification token for Customer

MUTATIONcustomerCreateEmailVerificationToken
Arguments
id​
String​
version​
Long​
ttlMinutes​
Int​

The validity of the created token in minutes.

storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

invalidateOlderTokens​
Boolean​

Invalidate older, previously created tokens when a new token is created.

Default: false​

Verify email of Customer

MUTATIONcustomerConfirmEmail

Verifies customer's email using a token.

Arguments
version​
Long​
tokenValue​
String​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

Output:Customer

Update Customer

MUTATIONupdateCustomer
Arguments
version​
Long​
actions​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Customer

Delete Customer

MUTATIONdeleteCustomer
Arguments
version​
Long​
personalDataErasure​
Boolean​
Default: false​
storeKey​

The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions.

id​
String​

Queries with specified ID

key​
String​

Queries with specified key

Output:Customer

Output types

Customer

A customer is a person purchasing products. Carts, Orders and Reviews can be associated to a customer.

id​
String​

Unique identifier of the Customer.

customerNumber​
String​

User-defined unique identifier of the Customer.

Can be used to refer to a Customer in a human-readable way (in emails, invoices, and other correspondence).

email​
String​
Email address of the Customer that is unique for an entire Project or to a Store the Customer is assigned to. It is the mandatory unique identifier of a Customer.
addresses​
Array of Address​

Addresses used by the Customer.

defaultShippingAddressId​
String​
ID of the address in addresses used as the default shipping address.
defaultBillingAddressId​
String​
ID of the address in addresses used as the default billing address.
shippingAddressIds​
Array of String​
IDs of addresses in addresses used as shipping addresses.
billingAddressIds​
Array of String​
IDs of addresses in addresses used as billing addresses.
isEmailVerified​
Boolean​
Indicates whether the email address of the Customer is verified.
customerGroupRef​
CustomerGroup to which the Customer belongs.
externalId​
String​

Optional identifier for use in external systems like customer relationship management (CRM) or enterprise resource planning (ERP).

key​
String​

User-defined unique identifier of the Customer.

authenticationMode​
Indicates whether the password is required for the Customer.
Can be ExternalAuth, or Password​
firstName​
String​

Given name (first name) of the Customer.

lastName​
String​

Family name (last name) of the Customer.

middleName​
String​

Middle name of the Customer.

title​
String​

Title of the Customer, for example, 'Dr.'.

locale​

Preferred language of the Customer.

salutation​
String​

Salutation of the Customer, for example, 'Mr.' or 'Mrs.'.

dateOfBirth​
Date​

Date of birth of the Customer.

companyName​
String​

Company name of the Customer.

vatId​
String​

Individual VAT ID of the Customer.

password​
String​
Present only when authenticationMode is set to Password.
customerGroup​
CustomerGroup to which the Customer belongs.
defaultShippingAddress​
defaultBillingAddress​
shippingAddresses​
Array of Address​
billingAddresses​
Array of Address​
storesRef​
Array of KeyReference​
Stores to which the Customer is assigned to.
stores​
Array of Store​
Stores to which the Customer is assigned to.
customerGroupAssignments​

Customer Groups that the Customer belongs to.

custom​

Custom Fields of the Customer.

version​
Long​

Current version of the Customer.

createdAt​

Date and time (UTC) the Customer was initially created.

lastModifiedAt​

Date and time (UTC) the Customer was last updated.

createdBy​

IDs and references that created the Customer.

lastModifiedBy​

IDs and references that last modified the Customer.

AuthenticationMode

ExternalAuth
Password

CustomerSignInResult

customer​
Customer signed up or signed in after authentication.
cart​
Cart​

Cart associated with the Customer.

The Cart is recalculated to remove invalid Line Items and apply the latest prices, taxes, and discounts. During these updates, the following errors can be returned: MatchingPriceNotFound and MissingTaxRateForCountry.
For more information, see Cart updates.

CustomerPasswordToken

customerId​
String​
expiresAt​
value​
String​
invalidateOlderTokens​
Boolean​
id​
String​
version​
Long​
createdAt​
lastModifiedAt​
createdBy​
lastModifiedBy​

CustomerEmailToken

customerId​
String​
expiresAt​
value​
String​
invalidateOlderTokens​
Boolean​
id​
String​
version​
Long​
createdAt​
lastModifiedAt​
createdBy​
lastModifiedBy​

CustomerGroupAssignment

customerGroupRef​

Reference to a Customer Group.

customerGroup​

Reference to a Customer Group.

CustomerQueryResult

offset​
Int​
count​
Int​
total​
Long​
exists​
Boolean​
results​
Array of Customer​

Input types

CustomerSignUpDraft

This type is equivalent to CustomerDraft in the REST API.
email​
String​
password​
String​
firstName​
String​
lastName​
String​
middleName​
String​
title​
String​
dateOfBirth​
Date​
companyName​
String​
vatId​
String​
addresses​
Array of AddressInput​
Default: []​
defaultBillingAddress​
Int​
The index of the address in the addresses list. The defaultBillingAddressId of the customer will be set to the ID of that address.
defaultShippingAddress​
Int​
The index of the address in the addresses list. The defaultShippingAddressId of the customer will be set to the ID of that address.
shippingAddresses​
Array of Int​
The indices of the shipping addresses in the addresses list. The shippingAddressIds of the Customer will be set to the IDs of that addresses.
Default: []​
billingAddresses​
Array of Int​
The indices of the billing addresses in the addresses list. The billingAddressIds of the customer will be set to the IDs of that addresses.
Default: []​
custom​
locale​
salutation​
String​
key​
String​
stores​
customerNumber​
String​
anonymousCartId​
String​

This field will be deprecated in favour of anonymousCart.id.

anonymousCart​
externalId​
String​
customerGroup​
customerGroupAssignments​
isEmailVerified​
Boolean​
anonymousId​
String​
authenticationMode​
Can be ExternalAuth, or Password​

AuthenticationMode

ExternalAuth
Password

CustomerSignInDraft

This type is equivalent to CustomerSignin in the REST API.
email​
String​
password​
String​
anonymousCartId​
String​

This field will be deprecated in favour of anonymousCart.id.

anonymousCart​
anonymousCartSignInMode​
Can be MergeWithExistingCustomerCart, or UseAsNewActiveCustomerCart​Default: MergeWithExistingCustomerCart​
anonymousId​
String​
updateProductData​
Boolean​
Default: false​

AnonymousCartSignInMode

MergeWithExistingCustomerCart
`LineItem`s of the anonymous cart will be copied to the customer’s active cart that has been modified most recently. The `CartState` of the anonymous cart gets changed to `Merged` while the `CartState` of the customer’s cart remains `Active`. `CustomLineItems` and `CustomFields` of the anonymous cart will not be copied to the customers cart. If a `LineItem` in the anonymous cart matches an existing line item in the customer’s cart (same product ID and variant ID), the maximum quantity of both LineItems is used as the new quantity. In that case `CustomFields` on the `LineItem` of the anonymous cart will not be in the resulting `LineItem`.
UseAsNewActiveCustomerCart
The anonymous cart is used as new active customer cart. No `LineItem`s get merged.

CustomerGroupAssignmentDraft

customerGroup​

ResourceIdentifier of a Customer Group.

CustomerUpdateAction

addAddress​
addBillingAddressId​
addCustomerGroupAssignment​
addShippingAddressId​
addStore​
changeAddress​
changeEmail​
removeAddress​
removeBillingAddressId​
removeCustomerGroupAssignment​
removeShippingAddressId​
removeStore​
setCompanyName​
setAddressCustomField​
setAddressCustomType​
setAuthenticationMode​
setCustomField​
setCustomType​
setCustomerGroup​
setCustomerGroupAssignments​
setKey​
setLocale​
setCustomerNumber​
setDateOfBirth​
setDefaultBillingAddress​
setDefaultShippingAddress​
setExternalId​
setFirstName​
setLastName​
setMiddleName​
setSalutation​
setStores​
setTitle​
setVatId​

Update actions

Add Address

Adding an address to the Customer produces the CustomerAddressAdded Message.
address​
Value to append to the addresses array.

Add Billing Address ID

Adds an Address from the addresses array to billingAddressIds. Either addressId or addressKey is required.
addressId​
String​
id of the Address to become a billing address.
addressKey​
String​
key of the Address to become a billing address.

Add Customer Group Assignment

customerGroupAssignment​

Add Shipping Address ID

Adds an Address from the addresses array to shippingAddressIds. Either addressId or addressKey is required.
addressId​
String​
id of the Address to become a shipping address.
addressKey​
String​
key of the Address to become a shipping address.

Add Store

Associates the Customer with a Store.

ResourceIdentifier of the Store to add.

Change Address

Changing an address of the Customer produces the CustomerAddressChanged Message.
Either addressId or addressKey is required.
addressId​
String​
id of the Address to change.
addressKey​
String​
key of the Address to change.
address​

Value to set.

Change Email

Changes the email of the Customer and sets the isEmailVerified property to false. This update action generates a CustomerEmailChanged Message.
email​
String​

Value to set.

Remove Address

Removing an address from the Customer produces the CustomerAddressRemoved Message.
Either addressId or addressKey is required.
addressId​
String​
id of the Address to remove.
addressKey​
String​
key of the Address to remove.

Remove Billing Address ID

Removes a billing address from billingAddressIds. If the billing address is the default billing address, the defaultBillingAddressId is unset. Either addressId or addressKey is required.
addressId​
String​
id of the Address to remove from billingAddressIds.
addressKey​
String​
key of the Address to remove from billingAddressIds.

Remove Customer Group Assignment

customerGroup​

Remove Shipping Address ID

Removes a shipping address from shippingAddressIds. If the shipping address is the default shipping address, the defaultShippingAddressId is unset. Either addressId or addressKey is required.
addressId​
String​
id of the Address to remove from shippingAddressIds.
addressKey​
String​
key of the Address to remove from shippingAddressIds.

Remove Store

Removes the association to a Store from the Customer. If no more Stores are assigned, the Customer becomes a global Customer.

ResourceIdentifier of the Store to remove.

Set Company Name

Setting a company name produces the CustomerCompanyNameSet Message.
companyName​
String​

Value to set. If omitted, any existing value is removed.

Set CustomField in Address

Adding a Custom Field to an Address of a Customer generates the CustomerAddressCustomFieldAdded Message, removing one generates the CustomerAddressCustomFieldRemoved Message, and updating an existing one generates the CustomerAddressCustomFieldChanged Message.
name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. If value is provided, it is set for the field defined by name. Trying to remove a field that does not exist will fail with an InvalidOperation error.
addressId​
String​
User-defined unique identifier of the Address to be updated.

Set Custom Type in Address

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​
addressId​
String​

Set AuthenticationMode

authMode​
Value to set. Changing a Customer's authMode from Password to ExternalAuth deletes the Customer's password.
Can be ExternalAuth, or Password​
password​
String​
Required when authMode is Password.

AuthenticationMode

ExternalAuth
Password

Set Custom Field

Adding a Custom Field to a Customer generates the CustomerCustomFieldAdded Message, removing one generates the CustomerCustomFieldRemoved Message, and updating an existing one generates the CustomerCustomFieldChanged Message.
name​
String​
Name of the Custom Field.
value​
String​
If value is absent or null, this field will be removed if it exists. If value is provided, it is set for the field defined by name. Trying to remove a field that does not exist will fail with an InvalidOperation error.

Set Custom Type

fields​
Array of CustomFieldInput​
typeKey​
String​
typeId​
String​

Set Customer Group

customerGroup​

Set Customer Group Assignments

customerGroupAssignments​

Set Key

key​
String​
If key is absent or null, the existing key, if any, will be removed.

Set Locale

locale​
Value to set. Must be one of the languages supported by the Project.

Set Customer Number

customerNumber​
String​

Set Date of Birth

Setting the date of birth of the Customer produces the CustomerDateOfBirthSet Message.
dateOfBirth​
Date​

Value to set. If omitted, any existing value is removed.

Set Default Billing Address

Sets the default billing address from addresses. The action adds the id of the specified Address to the billingAddressIds if not contained already. Either addressId or addressKey is required.
This action generates the CustomerDefaultBillingAddressSet Message.
addressId​
String​
id of the Address to become the default billing address.
addressKey​
String​
key of the Address to become the default billing address.

Set Default Shipping Address

Sets the default shipping address from addresses. The action adds the id of the specified address to the shippingAddressIds if not contained already. Either addressId or addressKey is required.
This action generates the CustomerDefaultShippingAddressSet Message.
addressId​
String​
id of the Address to become the default shipping address.
addressKey​
String​
key of the Address to become the default shipping address.

Set External ID

This action generates the CustomerExternalIdSet Message.
externalId​
String​

Value to set. If omitted, any existing value is removed.

Set First Name

Setting the first name of the Customer produces the CustomerFirstNameSet Message.
firstName​
String​

Value to set. If omitted, any existing value is removed.

Set Last Name

Setting the last name of the Customer produces the CustomerLastNameSet Message.
lastName​
String​

Value to set. If omitted, any existing value is removed.

Set Middle Name

middleName​
String​

Value to set. If omitted, any existing value is removed.

Set Salutation

salutation​
String​

Value to set. If omitted, any existing value is removed.

Set Stores

Sets the Stores the Customer account is associated with. If no Stores are specified, the Customer becomes a global Customer.
This action generates the CustomerStoresSet Message.
stores​

ResourceIdentifier of the Stores to set.

Set Title

Setting the title of the Customer produces the CustomerTitleSet Message.
title​
String​

Value to set. If omitted, any existing value is removed.

Set Vat ID

vatId​
String​

Value to set. If omitted, any existing value is removed.