Queries and mutations for managing Customers in the platform.
Queries
Query Customers
| Arguments | |
|---|---|
whereString | |
sortArray of String | |
limitInt | |
offsetInt | |
Get Customer
| Arguments | |
|---|---|
emailTokenString | Queries a customer with specified email token |
passwordTokenString | Queries a customer with specified password token |
idString | Queries with specified ID |
keyString | Queries with specified key |
Mutations
Create (sign up) Customer
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
Retrieves the authenticated customer (a customer that matches the given email/password pair).
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.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 theCartStateof the anonymous cart gets changed toMergedwhile the customer's cart remains theActivecart.If aLineItemin the anonymous cart matches an existing line item, or aCustomLineItemmatches an existing custom line item in the customer's cart, the maximum quantity of both line items is used as the new quantity.ItemShippingDetailsare copied from the item with the highest quantity.IfitemShippingAddressesare 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).
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
Create password reset token for Customer
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 | |
|---|---|
emailString | |
ttlMinutesInt | 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. |
invalidateOlderTokensBoolean | Invalidate older, previously created tokens when a new token is created. Default:false |
Reset password of Customer
The following workflow can be used to reset the customer’s password:
- Create a password reset token and send it embedded in a link to the customer.
- When the customer clicks on the link, you may optionally retrieve customer by password token.
- When the customer entered new password, use reset customer’s password to reset the password.
| Arguments | |
|---|---|
versionLong | |
tokenValueString | |
newPasswordString | |
storeKey | The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions. |
Create email verification token for Customer
| Arguments | |
|---|---|
idString | |
versionLong | |
ttlMinutesInt | 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. |
invalidateOlderTokensBoolean | Invalidate older, previously created tokens when a new token is created. Default:false |
Verify email of Customer
Update Customer
| Arguments | |
|---|---|
versionLong | |
actionsArray of CustomerUpdateAction | |
storeKey | The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions. |
idString | Queries with specified ID |
keyString | Queries with specified key |
Delete Customer
| Arguments | |
|---|---|
versionLong | |
personalDataErasureBoolean | Default: false |
storeKey | The mutation is only performed if the resource is part of the store. Can be used with store-specific OAuth permissions. |
idString | Queries with specified ID |
keyString | Queries with specified key |
Output types
Customer
A customer is a person purchasing products. Carts, Orders and Reviews can be associated to a customer.
idString | Unique identifier of the Customer. |
customerNumberString | 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). |
emailString | 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. |
addressesArray of Address | Addresses used by the Customer. |
defaultShippingAddressIdString | ID of the address in addresses used as the default shipping address. |
defaultBillingAddressIdString | ID of the address in addresses used as the default billing address. |
shippingAddressIdsArray of String | IDs of addresses in addresses used as shipping addresses. |
billingAddressIdsArray of String | IDs of addresses in addresses used as billing addresses. |
isEmailVerifiedBoolean | Indicates whether the email address of the Customer is verified. |
customerGroupRef | CustomerGroup to which the Customer belongs. |
externalIdString | Optional identifier for use in external systems like customer relationship management (CRM) or enterprise resource planning (ERP). |
keyString | User-defined unique identifier of the Customer. |
authenticationMode | Indicates whether the Can be password is required for the Customer.ExternalAuth, or Password |
firstNameString | Given name (first name) of the Customer. |
lastNameString | Family name (last name) of the Customer. |
middleNameString | Middle name of the Customer. |
titleString | Title of the Customer, for example, 'Dr.'. |
locale | Preferred language of the Customer. |
salutationString | Salutation of the Customer, for example, 'Mr.' or 'Mrs.'. |
dateOfBirthDate | Date of birth of the Customer. |
companyNameString | Company name of the Customer. |
vatIdString | Individual VAT ID of the Customer. |
passwordString | Present only when authenticationMode is set to Password. |
customerGroup | CustomerGroup to which the Customer belongs. |
defaultShippingAddress | |
defaultBillingAddress | |
shippingAddressesArray of Address | |
billingAddressesArray of Address | |
storesRefArray of KeyReference | Stores to which the Customer is assigned to.
|
storesArray of Store | Stores to which the Customer is assigned to.
|
customerGroupAssignmentsArray of CustomerGroupAssignment | Customer Groups that the Customer belongs to. Used for Line Item price selection. |
custom | Custom Fields of the Customer. |
versionLong | 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
ExternalAuthPassword
CustomerSignInResult
customer | |
cartCart | 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
CustomerEmailToken
CustomerGroupAssignment
customerGroupRef | Reference to a Customer Group. |
customerGroup | Reference to a Customer Group. |
CustomerQueryResult
Input types
CustomerSignUpDraft
emailString | |
passwordString | |
firstNameString | |
lastNameString | |
middleNameString | |
titleString | |
dateOfBirthDate | |
companyNameString | |
vatIdString | |
addressesArray of AddressInput | Default: [] |
defaultBillingAddressInt | The index of the address in the addresses list. The defaultBillingAddressId of the customer will be set to the ID of that address. |
defaultShippingAddressInt | The index of the address in the addresses list. The defaultShippingAddressId of the customer will be set to the ID of that address. |
shippingAddressesArray of Int | The indices of the shipping addresses in the Default: addresses list. The shippingAddressIds of the Customer will be set to the IDs of that addresses.[] |
billingAddressesArray of Int | The indices of the billing addresses in the Default: addresses list. The billingAddressIds of the customer will be set to the IDs of that addresses.[] |
custom | |
locale | |
salutationString | |
keyString | |
storesArray of ResourceIdentifierInput | |
customerNumberString | |
anonymousCartIdString | This field will be deprecated in favour of anonymousCart.id. |
anonymousCart | |
externalIdString | |
customerGroup | |
customerGroupAssignmentsArray of CustomerGroupAssignmentDraft | |
isEmailVerifiedBoolean | |
anonymousIdString | |
authenticationMode | Can be ExternalAuth, or Password |
AuthenticationMode
ExternalAuthPassword
CustomerSignInDraft
emailString | |
passwordString | |
anonymousCartIdString | This field will be deprecated in favour of anonymousCart.id. |
anonymousCart | |
anonymousCartSignInMode | Can be MergeWithExistingCustomerCart, or UseAsNewActiveCustomerCartDefault: MergeWithExistingCustomerCart |
anonymousIdString | |
updateProductDataBoolean | 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
address | Value to append to the addresses array. |
Add Billing Address ID
Add Customer Group Assignment
customerGroupAssignment |
Add Shipping Address ID
Add Store
Associates the Customer with a Store.
store | ResourceIdentifier of the Store to add. |
Change Address
addressId or addressKey is required.Change Email
email of the Customer and sets the isEmailVerified property to false. This update action generates a CustomerEmailChanged Message.emailString | Value to set. |
Remove Address
addressId or addressKey is required.Remove Billing Address ID
billingAddressIds.
If the billing address is the default billing address, the defaultBillingAddressId is unset. Either addressId or addressKey is required.Remove Customer Group Assignment
customerGroup |
Remove Shipping Address ID
shippingAddressIds.
If the shipping address is the default shipping address, the defaultShippingAddressId is unset. Either addressId or addressKey is required.Remove Store
store | ResourceIdentifier of the Store to remove. |
Set Company Name
companyNameString | Value to set. If omitted, any existing value is removed. |
Set CustomField in Address
nameString | Name of the Custom Field. |
valueString | 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. |
addressIdString | User-defined unique identifier of the Address to be updated. |
Set Custom Type in Address
fieldsArray of CustomFieldInput | |
type | |
typeKeyString | |
typeIdString | |
addressIdString |
Set AuthenticationMode
authMode | Value to set.
Changing a Customer's Can be authMode from Password to ExternalAuth deletes the Customer's password.ExternalAuth, or Password |
passwordString | Required when authMode is Password. |
AuthenticationMode
ExternalAuthPassword
Set Custom Field
nameString | Name of the Custom Field. |
valueString | 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
fieldsArray of CustomFieldInput | |
type | |
typeKeyString | |
typeIdString |
Set Customer Group
customerGroup |
Set Customer Group Assignments
customerGroupAssignmentsArray of CustomerGroupAssignmentDraft |
Set Key
keyString | If key is absent or null, the existing key, if any, will be removed. |
Set Locale
Set Customer Number
customerNumberString |
Set Date of Birth
dateOfBirthDate | Value to set. If omitted, any existing value is removed. |
Set Default Billing Address
addresses.
The action adds the id of the specified Address to the billingAddressIds if not contained already. Either addressId or addressKey is required.Set Default Shipping Address
addresses.
The action adds the id of the specified address to the shippingAddressIds if not contained already. Either addressId or addressKey is required.Set External ID
externalIdString | Value to set. If omitted, any existing value is removed. |
Set First Name
firstNameString | Value to set. If omitted, any existing value is removed. |
Set Last Name
lastNameString | Value to set. If omitted, any existing value is removed. |
Set Middle Name
middleNameString | Value to set. If omitted, any existing value is removed. |
Set Salutation
salutationString | Value to set. If omitted, any existing value is removed. |
Set Stores
storesArray of ResourceIdentifierInput | ResourceIdentifier of the Stores to set. |
Set Title
titleString | Value to set. If omitted, any existing value is removed. |
Set Vat ID
vatIdString | Value to set. If omitted, any existing value is removed. |