Reworked GraphQL tutorial

src/guides/v2.3/graphql/index.md

@@ -10,22 +10,22 @@ landing-page: GraphQL Developer's Guide
 
 As of Magento 2.3.4, GraphQL provides the following features:
 
-*  Support for all product types, payment methods, and shipping methods
-*  Achieved <.5 sec average response times with 500 concurrent requests
-*  Redesigned a feature rich layered navigation
+-  Support for all product types, payment methods, and shipping methods
+-  Achieved <.5 sec average response times with 500 concurrent requests
+-  Redesigned a feature rich layered navigation
 
 ## Where we're going
 
 The `graphql-ce` Community Engineering repository has been archived. Development for Magento 2.3.5 will be limited to bug fixes.
 
 For the 2.4.0 and 2.4.1 releases, Magento teams are working toward completing GraphQL coverage for Business to Consumer (B2C) uses cases, with emphasis on the following:
 
-*  Reorders
-*  Inventory Management store pickups
-*  Order history for logged in customers
-*  Replace product-specific mutations that add products to a cart with a single mutation that can handle all product types
-*  Gift wrapping and messages
-*  Saved payment methods
+-  Reorders
+-  Inventory Management store pickups
+-  Order history for logged in customers
+-  Replace product-specific mutations that add products to a cart with a single mutation that can handle all product types
+-  Gift wrapping and messages
+-  Saved payment methods
 
 We also expect to begin adding coverage for B2B scenarios.
 

src/guides/v2.3/graphql/tutorials/checkout/checkout-add-product-to-cart.md

@@ -31,9 +31,11 @@ If you add a product to the shopping cart as a registered customer, be sure to s
 
 ## Add a simple product into the shopping cart
 
-`{ CART_ID }` is the unique shopping cart ID from [Step 2. Create empty cart]({{ page.baseurl }}/graphql/tutorials/checkout/checkout-add-product-to-cart.html).
+The following mutation adds a simple product into the shopping cart.
 
-The following mutation adds a **simple product** into shopping cart.
+Replace `{ CART_ID }` with the unique shopping cart ID from [Step 2. Create empty cart]({{ page.baseurl }}/graphql/tutorials/checkout/checkout-add-product-to-cart.html).
+
+In this example, we will add the Aim Analog Watch (SKU 24-MG04) from the default Luma catalog to the cart. The SKU identifies the product to be added.
 
 **Request:**
 
@@ -46,7 +48,7 @@ mutation {
         {
           data: {
             quantity: 1
-            sku: "simple-product"
+            sku: "24-MG04"
           }
         }
       ]
@@ -75,9 +77,9 @@ mutation {
       "cart": {
         "items": [
           {
-            "id": "508",
+            "id": "5",
             "product": {
-              "sku": "simple-product",
+              "sku": "24-MG04",
               "stock_status": "IN_STOCK"
             },
             "quantity": 1
@@ -91,7 +93,8 @@ mutation {
 
 ## Add a virtual product into the shopping cart
 
-The following mutation adds a **virtual product** into shopping cart.
+The following mutation adds a virtual product into the shopping cart.
+In this example, we add the Beginner's Yoga video downloadable product (SKU 240-LV04).
 
 **Request:**
 
@@ -104,7 +107,7 @@ mutation {
         {
           data: {
             quantity: 1
-            sku: "virtual-product"
+            sku: "240-LV04"
           }
         }
       ]
@@ -133,9 +136,17 @@ mutation {
       "cart": {
         "items": [
           {
-            "id": "509",
+            "id": "5",
             "product": {
-              "sku": "virtual-product",
+              "sku": "24-MG04",
+              "stock_status": "IN_STOCK"
+            },
+            "quantity": 1
+          },
+          {
+            "id": "6",
+            "product": {
+              "sku": "240-LV04",
               "stock_status": "IN_STOCK"
             },
             "quantity": 1
@@ -147,6 +158,8 @@ mutation {
 }
 ```
 
+The response lists all items currently in the cart, including the just-added video download.
+
 ## Verify this step {#verify-step}
 
 1. Sign in as a customer to the website using the email `john.doe@example.com` and password `b1b2b3l@w+`.

src/guides/v2.3/graphql/tutorials/checkout/checkout-billing-address.md

@@ -25,53 +25,42 @@ Use the [setBillingAddressOnCart]({{ page.baseurl }}/graphql/mutations/set-billi
 
 ## Add a new billing address
 
-The following mutation adds a new billing address. `{ CART_ID }` is the unique shopping cart ID from [Step 2. Create empty cart]({{ page.baseurl }}/graphql/tutorials/checkout/checkout-add-product-to-cart.html).
+Similar to the previous step, we will add a billing address to the customer. `{ CART_ID }` is the unique shopping cart ID from [Step 2. Create empty cart]({{ page.baseurl }}/graphql/tutorials/checkout/checkout-add-product-to-cart.html). In this example, the `default_billing` parameter is set to `true`. The street address is also different, so we can see that different addresses are being created.
 
-**Request:**
+Send the customer's authorization token in the `Authorization` parameter of the header. See [Authorization tokens]({{page.baseurl}}/graphql/authorization-tokens.html) for more information.
 
-{:.bs-callout .bs-callout-info}
-For logged-in customers, send the customer's authorization token in the `Authorization` parameter of the header. See [Authorization tokens]({{page.baseurl}}/graphql/authorization-tokens.html) for more information.
+**Request:**
 
 ```graphql
 mutation {
-  setBillingAddressOnCart(
-    input: {
-      cart_id: "{ CART_ID }"
-      billing_address: {
-        address: {
-          firstname: "John"
-          lastname: "Doe"
-          company: "Company Name"
-          street: ["320 N Crescent Dr", "Beverly Hills"]
-          city: "Los Angeles"
-          region: "CA"
-          postcode: "90210"
-          country_code: "US"
-          telephone: "123-456-0000"
-          save_in_address_book: false
-        }
-      }
+  createCustomerAddress(input: {
+    region: {
+      region: "Arizona"
+      region_code: "AZ"
+      region_id: 4
     }
-  ) {
-    cart {
-      billing_address {
-        firstname
-        lastname
-        company
-        street
-        city
-        region{
-          code
-          label
-        }
-        postcode
-        telephone
-        country {
-          code
-          label
-        }
-      }
+    country_code: US
+    street: ["123 Stone Ave."]
+    telephone: "7777777777"
+    postcode: "77777"
+    city: "Phoenix"
+    firstname: "Bob"
+    lastname: "Loblaw"
+    default_shipping: false
+    default_billing: true
+  }) {
+    id
+    region {
+      region
+      region_code
     }
+    country_code
+    street
+    telephone
+    postcode
+    city
+    default_shipping
+    default_billing
   }
 }
 ```
@@ -81,41 +70,37 @@ mutation {
 ```json
 {
   "data": {
-    "setBillingAddressOnCart": {
-      "cart": {
-        "billing_address": {
-          "firstname": "John",
-          "lastname": "Doe",
-          "company": "Company Name",
-          "street": [
-            "320 N Crescent Dr",
-            "Beverly Hills"
-          ],
-          "city": "Los Angeles",
-          "region": {
-            "code": "CA",
-            "label": "California"
-          },
-          "postcode": "90210",
-          "telephone": "123-456-0000",
-          "country": {
-            "code": "US",
-            "label": "US"
-          }
-        }
-      }
+    "createCustomerAddress": {
+      "id": 3,
+      "region": {
+        "region": "Arizona",
+        "region_code": "AZ"
+      },
+      "country_code": "US",
+      "street": [
+        "123 Stone Ave."
+      ],
+      "telephone": "7777777777",
+      "postcode": "77777",
+      "city": "Phoenix",
+      "default_shipping": false,
+      "default_billing": true
     }
   }
 }
 ```
 
-## Add a new address for billing and shipping
+## Same address for billing and shipping
+
+So far, we have created separate billing and shipping addresses and added them to the customer record.
 
-The following mutation includes the `same_as_shipping` attribute, which allows the same address to be used for billing and shipping.
+A common scenario is using the same address for both billing and shipping. A common pattern offers the ability to use the same address for both.
+
+The following mutation includes the `same_as_shipping` attribute, which allows the same address to be used for billing and shipping on the cart.
 
 **Request:**
 
-```text
+```graphql
 mutation {
   setBillingAddressOnCart(
     input: {
@@ -224,13 +209,16 @@ mutation {
 }
 ```
 
+We can confirm that the same address is specified for both addresses.
+
 ## Use an existing customer address
 
+If you wish to change one of the addresses to use existing addresses, that is as follows.
 First, query the customer to return the list of address IDs.
 
 **Request:**
 
-```text
+```graphql
 query {
   customer {
     addresses {
@@ -244,14 +232,20 @@ query {
 
 **Response:**
 
-```text
+```json
+{
   "data": {
     "customer": {
       "addresses": [
         {
           "id": 2,
-          "default_billing": true,
+          "default_billing": false,
           "default_shipping": true
+        },
+        {
+          "id": 3,
+          "default_billing": true,
+          "default_shipping": false
         }
       ]
     }
@@ -263,9 +257,11 @@ Set `{ CUSTOMER_ADDRESS_ID }` to an `id` returned in the query.
 
 `{ CART_ID }` is the unique shopping cart ID from [Step 2. Create empty cart]({{ page.baseurl }}/graphql/tutorials/checkout/checkout-add-product-to-cart.html).
 
+Using the results from above, we can set the `{ CUSTOMER_ADDRESS_ID}` to `3` to use the default billing address.
+
 **Request:**
 
-```text
+```graphql
 mutation {
   setBillingAddressOnCart(
     input: {
@@ -306,20 +302,19 @@ mutation {
     "setBillingAddressOnCart": {
       "cart": {
         "billing_address": {
-          "firstname": "John",
-          "lastname": "Doe",
-          "company": "Company Name",
+          "firstname": "Bob",
+          "lastname": "Loblaw",
+          "company": null,
           "street": [
-            "320 N Crescent Dr",
-            "Beverly Hills"
+            "123 Stone Ave."
           ],
-          "city": "Los Angeles",
+          "city": "Phoenix",
           "region": {
-            "code": "CA",
-            "label": "California"
+            "code": "AZ",
+            "label": "Arizona"
           },
-          "postcode": "90210",
-          "telephone": "123-456-0000",
+          "postcode": "77777",
+          "telephone": "7777777777",
           "country": {
             "code": "US",
             "label": "US"
@@ -331,6 +326,8 @@ mutation {
 }
 ```
 
+The value of the `street` attribute ("123 Stone Ave.") is the default billing address we created at the beginning of this page.
+
 ## Verify this step {#verify-step}
 
 1. Sign in as a customer to the website using the email `john.doe@example.com` and password `b1b2b3l@w+`.