GraphQL: New mutations for managing customers

src/_data/toc/graphql.yml

@@ -164,6 +164,10 @@ pages:
         - label: createCustomer mutation
           url: /graphql/mutations/create-customer.html
 
+        - label: createCustomerV2 mutation
+          url: /graphql/mutations/create-customer-v2.html
+          exclude_versions: ["2.3"]
+
         - label: createCustomerAddress mutation
           url: /graphql/mutations/create-customer-address.html
 
@@ -255,6 +259,14 @@ pages:
         - label: updateCustomer mutation
           url: /graphql/mutations/update-customer.html
 
+        - label: updateCustomerEmail mutation
+          url: /graphql/mutations/update-customer-email.html
+          exclude_versions: ["2.3"]
+
+        - label: updateCustomerV2 mutation
+          url: /graphql/mutations/update-customer-v2.html
+          exclude_versions: ["2.3"]
+
         - label: updateCustomerAddress mutation
           url: /graphql/mutations/update-customer-address.html
 

src/guides/v2.4/graphql/mutations/create-customer-v2.md

@@ -0,0 +1,101 @@
+---
+group: graphql
+title: createCustomerV2 mutation
+---
+
+The `createCustomerV2` mutation creates a customer account. Use the [`createCustomerAddress` mutation]({{page.baseurl}}/graphql/mutations/create-customer-address.html) to complete the customer profile and define billing and shipping addresses.
+
+The `createCustomerV2` mutation replaces the `createCustomer` mutation as the means to create a customer account. The input objects differ between these two mutations. The `createCustomer` mutation required the `CustomerInput` object, as did the `updateCustomer` mutation. The attributes required for creating a customer are different than those for updating a customer, but you could not determine this by looking at the schema. The `createCustomerV2` mutation requires the `CustomerCreateInput` object, which it does not share with the [`updateCustomerV2` mutation]({{page.baseurl}}/graphql/mutations/update-customer-v2.html).
+
+## Syntax
+
+`mutation: {createCustomerV2(input: CustomerCreateInput!) {CustomerOutput}}`
+
+## Example usage
+
+The following call creates a new customer.
+
+**Request:**
+
+```graphql
+mutation {
+  createCustomer(
+    input: {
+      firstname: "Bob"
+      lastname: "Loblaw"
+      email: "[email protected]"
+      password: "b0bl0bl@w"
+      is_subscribed: true
+    }
+  ) {
+    customer {
+      firstname
+      lastname
+      email
+      is_subscribed
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "createCustomer": {
+      "customer": {
+        "firstname": "Bob",
+        "lastname": "Loblaw",
+        "email": "[email protected]",
+        "is_subscribed": true
+      }
+    }
+  }
+}
+```
+
+## Input attributes
+
+The following table lists the attributes you can use as input for the `createCustomerV2` mutation.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`date_of_birth` | String | The customer’s date of birth
+`dob` | String | Deprecated. Use `date_of_birth` instead. The customer’s date of birth
+`email` | String! | The customer’s email address
+`firstname` | String! | The customer’s first name
+`gender` | Int | The customer's gender (Male - 1, Female - 2)
+`is_subscribed` | Boolean | Indicates whether the customer subscribes to the store's newsletter
+`lastname` | String! | The customer’s last name
+`middlename` | String | The customer’s middle name
+`password` | String | The customer's password
+`prefix` | String | An honorific, such as Dr., Mr., or Mrs.
+`suffix` | String | A value such as Sr., Jr., or III
+`taxvat` | String | The customer’s Tax/VAT number (for corporate customers)
+
+## Output attributes
+
+The `CustomerOutput` object contains the `Customer` object.
+
+The following table lists the top-level attributes of the `customer` object. See the [`customer` query]({{page.baseurl}}/graphql/queries/customer.html) for complete details about this object.
+
+{% include graphql/customer-output-24.md %}
+
+## Errors
+
+Error | Description
+--- | ---
+`A customer with the same email address already exists in an associated website.` | The email provided in the `input`.`email` argument belongs to an existing customer.
+`"Email" is not a valid email address.` | The value provided in the `input`.`email` argument has an invalid format.
+`Field CustomerInput.email of required type String! was not provided` | The `input`.`email` argument was omitted.
+`Field "xxx" is not defined by type CustomerInput.` | The `input`.`xxx` argument is undefined.
+`Required parameters are missing: First Name` | The `input`.`firstname` argument was omitted or contains an empty value.
+
+## Related topics
+
+*  [customer query]({{page.baseurl}}/graphql/queries/customer.html)
+*  [updateCustomerV2 mutation]({{page.baseurl}}/graphql/mutations/update-customer-v2.html)
+*  [createCustomerAddress mutation]({{page.baseurl}}/graphql/mutations/create-customer-address.html)
+*  [updateCustomerAddress mutation]({{page.baseurl}}/graphql/mutations/update-customer-address.html)
+*  [deleteCustomerAddress mutation]({{page.baseurl}}/graphql/mutations/delete-customer-address.html)

src/guides/v2.4/graphql/mutations/create-customer.md

@@ -3,6 +3,9 @@ group: graphql
 title: createCustomer mutation
 ---
 
+{:.bs-callout-warning}
+The `createCustomer` mutation has been deprecated. Use the [createCustomerV2]({{page.baseurl}}/graphql/mutations/create-customer-v2.html) mutation instead.
+
 Use the `createCustomer` mutation to create a new customer.
 
 To return or modify information about a customer, Magento recommends you use customer tokens in the header of your GraphQL calls. However, you also can use [session authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-session.html).

src/guides/v2.4/graphql/mutations/update-customer-email.md

@@ -0,0 +1,64 @@
+---
+group: graphql
+title: updateCustomerEmail mutation
+---
+
+Use the `updateCustomerEmail` mutation to change the email address for the logged-in customer.
+
+To return or modify information about a customer, Magento recommends you use customer tokens in the header of your GraphQL calls. However, you also can use [session authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-session.html).
+
+## Syntax
+
+`mutation: updateCustomerEmail(email: String! password: String!): CustomerOutput`
+
+## Example usage
+
+The following call updates the customer's email address.
+
+**Request:**
+
+```graphql
+mutation {
+  updateCustomerEmail(email: "[email protected]", password: "[email protected]") {
+    customer {
+      email
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "updateCustomerEmail": {
+      "customer": {
+        "email": "[email protected]"
+      }
+    }
+  }
+}
+```
+
+## Input attributes
+
+The `updateCustomerEmail` mutation requires the following inputs:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`email` | String! | The customer's new email address
+`password` | String! | The customer's password
+
+## Output attributes
+
+The `updateCustomerEmail` mutation returns the `customer` object.
+
+The following table lists the top-level attributes of the `customer` object. See the [`customer` query]({{page.baseurl}}/graphql/queries/customer.html) for complete details about this object.
+
+{% include graphql/customer-output-24.md %}
+
+## Related topics
+
+*  [customer query]({{page.baseurl}}/graphql/queries/customer.html)
+*  [updateCustomerV2 mutation]({{page.baseurl}}/graphql/mutations/update-customer-v2.html)

src/guides/v2.4/graphql/mutations/update-customer-v2.md

@@ -0,0 +1,86 @@
+---
+group: graphql
+title: updateCustomerV2 mutation
+---
+
+The `updateCustomerV2` mutation updates the personal information in an existing customer account. Use the [`updateCustomerEmail` mutation]({{page.baseurl}}/graphql/mutations/update-customer-email.html) to update the customer's email address.
+
+The `updateCustomerV2` mutation replaces the `updateCustomer` mutation as the means to update a customer account. The input objects differ between these two mutations. The `updateCustomer` mutation required the `CustomerInput` object, as did the `createCustomer` mutation. Updating a customer does not require any specific attribute, while several attributes are required when you create a customer. You could not determine this by looking at the schema for those mutations. The `updateCustomerV2` mutation requires the `CustomerUpdateInput` object, which it does not share with the [`createCustomerV2` mutation]({{page.baseurl}}/graphql/mutations/create-customer-v2.html).
+
+To return or modify information about a customer, Magento recommends you use customer tokens in the header of your GraphQL calls. However, you also can use [session authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-session.html).
+
+## Syntax
+
+`mutation: {updateCustomerV2(input: CustomerUpdateInput!) {CustomerOutput}}`
+
+## Example usage
+
+The following call updates the first name and the newsletter subscription status for a specific customer.
+
+**Request:**
+
+```graphql
+mutation {
+  updateCustomerV2(
+    input: {
+      firstname: "Robert"
+      is_subscribed: false
+    }
+  ) {
+    customer {
+      firstname
+      is_subscribed
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "updateCustomerV2": {
+      "customer": {
+        "firstname": "Robert",
+        "is_subscribed": false
+      }
+    }
+  }
+}
+```
+
+## Input attributes
+
+The following table lists the attributes you can use as input for the `updateCustomerV2` mutation.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`date_of_birth` | String | The customer’s date of birth
+`dob` | String | Deprecated. Use `date_of_birth` instead. The customer’s date of birth
+`firstname` | String | The customer’s first name
+`gender` | Int | The customer's gender (Male - 1, Female - 2)
+`is_subscribed` | Boolean | Indicates whether the customer subscribes to the store's newsletter
+`lastname` | String | The customer’s last name
+`middlename` | String | The customer’s middle name
+`password` | String | The customer's password
+`prefix` | String | An honorific, such as Dr., Mr., or Mrs.
+`suffix` | String | A value such as Sr., Jr., or III
+`taxvat` | String | The customer’s Tax/VAT number (for corporate customers)
+
+## Output attributes
+
+The `CustomerOutput` object contains the `Customer` object.
+
+The following table lists the top-level attributes of the `customer` object. See the [`customer` query]({{page.baseurl}}/graphql/queries/customer.html) for complete details about this object.
+
+{% include graphql/customer-output-24.md %}
+
+## Related topics
+
+*  [customer query]({{page.baseurl}}/graphql/queries/customer.html)
+*  [createCustomerV2 mutation]({{page.baseurl}}/graphql/mutations/create-customer-v2.html)
+*  [createCustomerAddress mutation]({{page.baseurl}}/graphql/mutations/create-customer-address.html)
+*  [updateCustomerAddress mutation]({{page.baseurl}}/graphql/mutations/update-customer-address.html)
+*  [updateCustomerEmail mutation]({{page.baseurl}}/graphql/mutations/update-customer-email.html)
+*  [deleteCustomerAddress mutation]({{page.baseurl}}/graphql/mutations/delete-customer-address.html)

src/guides/v2.4/graphql/mutations/update-customer.md

@@ -3,6 +3,9 @@ group: graphql
 title: updateCustomer mutation
 ---
 
+{:.bs-callout-warning}
+The `updateCustomer` mutation has been deprecated. Use the [updateCustomerV2]({{page.baseurl}}/graphql/mutations/update-customer-v2.html) mutation instead.
+
 Use the `updateCustomer` mutation to update the customer's personal information.
 
 To return or modify information about a customer, Magento recommends you use customer tokens in the header of your GraphQL calls. However, you also can use [session authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication-session.html).