Account

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCE

Queries and mutations for the signed-in Customer and their address book.

Queries

Get signed-in Customer

QUERYme

Returns the signed-in Customer. Null for an anonymous or guest session.

Output:Customer
Request Example:graphql
query GetMe {
  me { id email emailVerified firstName lastName authMode }
}
Response Example:json
{
  "data": {
    "me": {
      "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "email": "jane.doe@example.com",
      "emailVerified": true,
      "firstName": "Jane",
      "lastName": "Doe",
      "authMode": "PASSWORD"
    }
  }
}

Mutations

Register Customer

MUTATIONregister

Creates a Customer.

It doesn't sign the Customer in. The current session stays valid and anonymous. To sign in, call POST /{project}/main/session with the password grant, which also moves the guest Cart to the new Customer.
Arguments
input​
RegisterInput​

Customer to create.

Output:CustomerResult
Request Example:graphql
mutation Register {
  register(
    input: {firstName: "Jane", lastName: "Doe", email: "jane.doe@example.com", password: "<password>"}
  ) {
    customer { id email emailVerified firstName lastName authMode }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "register": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "email": "jane.doe@example.com",
        "emailVerified": false,
        "firstName": "Jane",
        "lastName": "Doe",
        "authMode": "PASSWORD"
      },
      "userErrors": []
    }
  }
}

Update Customer profile

MUTATIONupdateProfile

Changes the first name, last name, or both, of the signed-in Customer.

Arguments
input​
UpdateProfileInput​

Names to change.

Output:CustomerResult
Request Example:graphql
mutation UpdateProfile {
  updateProfile(input: {firstName: "Janet"}) {
    customer { id firstName lastName }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "updateProfile": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "firstName": "Janet",
        "lastName": "Doe"
      },
      "userErrors": []
    }
  }
}

Set Customer middle name

MUTATIONsetMiddleName

Sets the middle name of the signed-in Customer.

Arguments
middleName​
String​

Middle name to set. Pass null to remove the existing value.

Output:CustomerResult
Request Example:graphql
mutation SetMiddleName {
  setMiddleName(middleName: "Rose") {
    customer { id firstName middleName lastName }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setMiddleName": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "firstName": "Jane",
        "middleName": "Rose",
        "lastName": "Doe"
      },
      "userErrors": []
    }
  }
}

Set Customer title

MUTATIONsetTitle

Sets the title of the signed-in Customer.

Arguments
title​
String​

Title to set. Pass null to remove the existing value.

Output:CustomerResult
Request Example:graphql
mutation SetTitle {
  setTitle(title: "Dr.") {
    customer { id title }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setTitle": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "title": "Dr."
      },
      "userErrors": []
    }
  }
}

Set Customer salutation

MUTATIONsetSalutation

Sets the salutation of the signed-in Customer.

Arguments
salutation​
String​

Salutation to set. Pass null to remove the existing value.

Output:CustomerResult
Request Example:graphql
mutation SetSalutation {
  setSalutation(salutation: "Ms.") {
    customer { id salutation }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setSalutation": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "salutation": "Ms."
      },
      "userErrors": []
    }
  }
}

Set Customer date of birth

MUTATIONsetDateOfBirth

Sets the date of birth of the signed-in Customer.

Arguments
dateOfBirth​
Date​
Date of birth to set, for example 1990-05-15. Pass null to remove the existing value.
Output:CustomerResult
Request Example:graphql
mutation SetDateOfBirth {
  setDateOfBirth(dateOfBirth: "1990-05-15") {
    customer { id dateOfBirth }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setDateOfBirth": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "dateOfBirth": "1990-05-15"
      },
      "userErrors": []
    }
  }
}

Set Customer company name

MUTATIONsetCompanyName

Sets the company name of the signed-in Customer.

Arguments
companyName​
String​

Company name to set. Pass null to remove the existing value.

Output:CustomerResult
Request Example:graphql
mutation SetCompanyName {
  setCompanyName(companyName: "Acme Corp") {
    customer { id companyName }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setCompanyName": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "companyName": "Acme Corp"
      },
      "userErrors": []
    }
  }
}

Set Customer VAT ID

MUTATIONsetVatId

Sets the individual VAT ID of the signed-in Customer.

Arguments
vatId​
String​

VAT ID to set. Pass null to remove the existing value.

Output:CustomerResult
Request Example:graphql
mutation SetVatId {
  setVatId(vatId: "GB123456789") {
    customer { id vatId }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setVatId": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "vatId": "GB123456789"
      },
      "userErrors": []
    }
  }
}

Change Customer password

MUTATIONchangePassword

Changes the password of the signed-in Customer.

This ends the session. Changing the password invalidates every token issued to the Customer, so the next request with this session is rejected. Sign in again with the new password.

Arguments
currentPassword​
String​
Current password of the Customer. A wrong value returns INVALID_CURRENT_PASSWORD.
newPassword​
String​

Password to set.

Output:CustomerResult
Request Example:graphql
mutation ChangePassword {
  changePassword(
    currentPassword: "<current-password>"
    newPassword: "<new-password>"
  ) {
    customer { id email }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "changePassword": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "email": "jane.doe@example.com"
      },
      "userErrors": []
    }
  }
}

Change Customer email

MUTATIONchangeEmail
Changes the email address of the signed-in Customer. Unlike changePassword, the session stays valid.
Arguments
input​
ChangeEmailInput​

Email change to apply.

Output:CustomerResult
Request Example:graphql
mutation ChangeEmail {
  changeEmail(input: {newEmail: "jane.doe@example.co.uk"}) {
    customer { id email emailVerified }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "changeEmail": {
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "email": "jane.doe@example.co.uk",
        "emailVerified": false
      },
      "userErrors": []
    }
  }
}

Add Customer address

MUTATIONaddAddress

Adds an address to the address book of the signed-in Customer. The new address isn't marked for shipping or billing.

An unrecognized country code returns SHIPPING_COUNTRY_NOT_SUPPORTED.
Arguments
input​
AddressBookInput​

Address to add.

Output:SavedAddressResult
Request Example:graphql
mutation AddAddress {
  addAddress(
    input: {name: "Jane Doe", line1: "10 Market Street", city: "London", postalCode: "EC2A 4NE", country: "GB"}
  ) {
    address { id name line1 city postalCode country }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "addAddress": {
      "address": {
        "id": "ARIDAURFREVERERFpEVERERFREUBCHBQMnJTNHRUAAEAAAAAAAEAAAABAAEAAA",
        "name": "Jane Doe",
        "line1": "10 Market Street",
        "city": "London",
        "postalCode": "EC2A 4NE",
        "country": "GB"
      },
      "userErrors": []
    }
  }
}

Update Customer address

MUTATIONupdateAddress
Updates an address in the address book of the signed-in Customer. An addressId that isn't in the address book returns ADDRESS_NOT_FOUND, and an unrecognized country code returns SHIPPING_COUNTRY_NOT_SUPPORTED.
Arguments
input​
UpdateAddressInput​

Address to update and its new values.

Output:SavedAddressResult
Request Example:graphql
mutation UpdateAddress {
  updateAddress(
    input: {addressId: "ARIDAURFREVERERFpEVERERFREUBCGFDM2RFNWZGAAEAAAAAAAEAAAABAAEAAA", address: {name: "Jane Doe", line1: "1 Example Street", line2: "Flat 2", city: "London", postalCode: "SW1A 1AA", country: "GB"}}
  ) {
    address { id line1 line2 city postalCode }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "updateAddress": {
      "address": {
        "id": "ARIDAURFREVERERFpEVERERFREUBCGFDM2RFNWZGAAEAAAAAAAEAAAABAAEAAA",
        "line1": "1 Example Street",
        "line2": "Flat 2",
        "city": "London",
        "postalCode": "SW1A 1AA"
      },
      "userErrors": []
    }
  }
}

Remove Customer address

MUTATIONremoveAddress
Removes an address from the address book of the signed-in Customer. An id that isn't in the address book returns ADDRESS_NOT_FOUND.
Arguments
id​
ID​
id of the SavedAddress to remove.
Output:SavedAddressResult
Request Example:graphql
mutation RemoveAddress {
  removeAddress(
    id: "ARIDAURFREVERERFpEVERERFREUBCHBQMnJTNHRUAAEAAAAAAAEAAAABAAEAAA"
  ) {
    address { id line1 city }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "removeAddress": {
      "address": {
        "id": "ARIDAURFREVERERFpEVERERFREUBCHBQMnJTNHRUAAEAAAAAAAEAAAABAAEAAA",
        "line1": "10 Market Street",
        "city": "London"
      },
      "userErrors": []
    }
  }
}

Set default Customer address

MUTATIONsetDefaultAddress
Makes an address the default shipping or billing address of the signed-in Customer and marks it for that use. An addressId that isn't in the address book returns ADDRESS_NOT_FOUND.
Arguments
addressId​
ID​
id of the SavedAddress to make the default.
use​
AddressUse​

Whether to make it the default shipping or the default billing address.

Can be SHIPPING, or BILLING​
Output:SavedAddressResult
Request Example:graphql
mutation SetDefaultAddress {
  setDefaultAddress(
    addressId: "ARIDAURFREVERERFpEVERERFREUBCGFDM2RFNWZGAAEAAAAAAAEAAAABAAEAAA"
    use: BILLING
  ) {
    address { id line1 isDefaultBilling usableForBilling }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setDefaultAddress": {
      "address": {
        "id": "ARIDAURFREVERERFpEVERERFREUBCGFDM2RFNWZGAAEAAAAAAAEAAAABAAEAAA",
        "line1": "1 Example Street",
        "isDefaultBilling": true,
        "usableForBilling": true
      },
      "userErrors": []
    }
  }
}

Output types

Customer

Account of the signed-in Customer.

id​
ID​

Unique identifier of the Customer.

key​
String​

User-defined unique identifier of the Customer.

firstName​
String​

Given name (first name) of the Customer. Empty string if not set.

lastName​
String​

Family name (last name) of the Customer. Empty string if not set.

middleName​
String​

Middle name of the Customer.

title​
String​
Title of the Customer, for example Dr..
salutation​
String​
Salutation of the Customer, for example Mr. or Ms..
dateOfBirth​
Date​
Date of birth of the Customer, for example 1990-05-15.
companyName​
String​

Company name of the Customer.

vatId​
String​

Individual VAT ID of the Customer.

customerNumber​
String​

Customer number assigned in the platform. No mutation in this API sets it.

email​
String​

Email address of the Customer.

emailVerified​
Boolean​
Whether the email address of the Customer is verified.
authMode​
AuthMode​

Authentication mode of the Customer.

Can be PASSWORD, or EXTERNAL_AUTH​
addresses​
Array of SavedAddress​

Addresses in the address book of the Customer.

_ctId​
ID​
Platform identifier (UUID) of the Customer, for extensions that key an external system such as a CRM by it. The public id is an opaque global identifier, so don't parse it.
Not part of the public API: an extension can read it with @requires, and it is removed from the composed API schema.

Saved Address

An entry in an address book: the signed-in Customer's own address book, or the address book of the selected Business Unit.

A Customer can always change their own address book. Changing a Business Unit's address book requires the UPDATE_BUSINESS_UNIT_DETAILS permission.
id​
ID​

Unique identifier of the address.

name​
String​
Name of the contact, made of the first and last name. If neither is set, contains the company value.
title​
String​
Title of the contact, for example Dr..
salutation​
String​
Salutation of the contact, for example Mr. or Ms..
company​
String​

Name of the company.

line1​
String​

Street name and street number.

line2​
String​

Further information on the street address.

additionalAddressInfo​
String​

Further information on the address.

poBox​
String​

Post office box number.

building​
String​

Number or name of the building.

apartment​
String​

Number or name of the apartment.

department​
String​

Name of the department.

city​
String​

Name of the city.

state​
String​
Name of the state or province, for example Colorado. In a country that taxes by state, tax selection matches on this value.
region​
String​

Name of the region, for locales that use a region that is not a state.

postalCode​
String​

Postal code.

country​
String​
Two-letter country code as per ISO 3166-1 alpha-2, for example GB.
phone​
String​

Phone number of the contact.

mobile​
String​

Mobile phone number of the contact.

fax​
String​

Fax number of the contact.

isDefaultShipping​
Boolean​

Whether this address is the default shipping address of the address book.

isDefaultBilling​
Boolean​

Whether this address is the default billing address of the address book.

usableForShipping​
Boolean​

Whether the address is marked for shipping.

The mark does not restrict anything: checkout accepts any address in the address book. setDefaultAddress marks the address for the use it makes it the default for, so a default address always reports true. If no address is marked, every address reports false.
usableForBilling​
Boolean​
Whether the address is marked for billing. Same rules as usableForShipping.

Auth Mode

How a Customer authenticates. Mirrors the AuthenticationMode of the Customer.
PASSWORD
The Customer signs in with an email address and password.
EXTERNAL_AUTH
The Customer is authenticated by an external system and has no password in the platform.

Address Use

Use that a saved address can be the default for.

SHIPPING
The address is used for shipping.
BILLING
The address is used for billing.

Customer Result

Result of a mutation on the signed-in Customer.

customer​
Customer​

The Customer after the mutation. Null if the mutation failed.

userErrors​
Array of UserError​

Reasons the mutation was refused. Empty on success.

Saved Address Result

Result of a mutation on an address book.

address​
SavedAddress​
The address the mutation acted on. For removeAddress, the removed address as it was. null if the mutation is refused, and after a successful removeBusinessUnitAddress. Check userErrors to tell these cases apart.
userErrors​
Array of UserError​

Reasons the mutation was refused. Empty on success.

Input types

Register Input

Profile and credentials of a new Customer.

firstName​
String​

Given name (first name) of the Customer.

lastName​
String​

Family name (last name) of the Customer.

email​
String​
Email address of the Customer. An address already used by another Customer returns EMAIL_ALREADY_IN_USE.
password​
String​
Password of the Customer. An empty password returns FORBIDDEN_ACTION.

Update Profile Input

Names to change on the signed-in Customer. Fields you omit or pass as null keep their current value.

firstName​
String​

New given name (first name) of the Customer.

lastName​
String​

New family name (last name) of the Customer.

Change Email Input

Email change for the signed-in Customer.

newEmail​
String​
Email address to set. An address already used by another Customer returns EMAIL_ALREADY_IN_USE.

Address Book Input

Address to save in an address book.

When it updates an existing address, fields this input doesn't contain, such as company or phone, keep their stored values. Omitting line2, state, or region clears them.
name​
String​

Name of the contact.

line1​
String​

Street name and street number.

line2​
String​

Further information on the street address.

city​
String​

Name of the city.

state​
String​
Name of the state or province, for example Colorado. In a country that taxes by state, tax selection matches on this value.
region​
String​

Name of the region, for locales that use a region that is not a state.

postalCode​
String​

Postal code.

country​
String​
Two-letter country code as per ISO 3166-1 alpha-2, for example GB.

Update Address Input

Identifies a saved address and carries its new values.

addressId​
ID​
id of the SavedAddress to update.
address​
AddressBookInput​

New values for the address.