Draft: Reorg GraphQL quote topic (#4502)

* checkpoint * fix broken links * one mutation per topic * Add consistency between topics * Apply suggestions from code review Co-Authored-By: Erik Marr <45772211+erikmarr@users.noreply.github.com> * incorporate review comments
magento · May 17, 2019 · b3c7efb · b3c7efb
1 parent 7ab9994
commit b3c7efb
Show file tree

Hide file tree

Showing 20 changed files with 1,961 additions and 499 deletions.
diff --git a/_data/toc/graphql.yml b/_data/toc/graphql.yml
@@ -86,8 +86,48 @@ pages:
                 - label: GroupedProduct endpoint
                   url: /graphql/reference/grouped-product.html
 
-            - label: Quote endpoint
+            - label: Quote endpoint (cart query)
               url: /graphql/reference/quote.html
+              children: 
+
+                - label: addSimpleProductsToCart mutation
+                  url: /graphql/reference/quote-add-simple-products.html
+
+                - label: addVirtualProductsToCart mutation
+                  url: /graphql/reference/quote-add-virtual-products.html
+
+                - label: applyCouponToCart mutation
+                  url: /graphql/reference/quote-apply-coupon.html
+
+                - label: createEmptyCart mutation
+                  url: /graphql/reference/quote-create-cart.html
+
+                - label: placeOrder mutation
+                  url: /graphql/reference/quote-place-order.html
+
+                - label: removeCouponFromCart mutation
+                  url: /graphql/reference/quote-remove-coupon.html
+
+                - label: removeItemFromCart mutation
+                  url: /graphql/reference/quote-remove-item.html
+
+                - label: setBillingAddressesOnCart mutation
+                  url: /graphql/reference/quote-set-billing-address.html
+
+                - label: setGuestEmailOnCart mutation
+                  url: /graphql/reference/quote-set-guest-email.html
+
+                - label: setPaymentMethodOnCart mutation
+                  url: /graphql/reference/quote-payment-method.html
+
+                - label: setShippingAddressesOnCart mutation
+                  url: /graphql/reference/quote-set-shipping-address.html
+
+                - label: setShippingMethodsOnCart mutation
+                  url: /graphql/reference/quote-shipping-method.html
+
+                - label: updateCartItems mutation
+                  url: /graphql/reference/quote-update-cart-items.html
 
             - label: Sales endpoint
               url: /graphql/reference/sales.html

diff --git a/_includes/graphql/cart-address-input.md b/_includes/graphql/cart-address-input.md
@@ -0,0 +1,12 @@
+Attribute |  Data Type | Description
+--- | --- | ---
+`city` | String! | The city specified for the billing or shipping address 
+`company` | String | The company specified for the billing or shipping address
+`country_code` | String! | The country code and label for the billing or shipping address
+`firstname` | String! | The customer's first name
+`lastname` | String! | The customer's last name
+`postcode` | String | The postal code for the billing or shipping address
+`region` | String | The region code and label for the billing or shipping address
+`save_in_address_book` | Boolean! | Specifies whether to save the address (`True`/`False`)
+`street` | [String]! | An array containing the street for the billing or shipping address
+`telephone` | String | The telephone number for the billing or shipping address
diff --git a/_includes/graphql/cart-item-input.md b/_includes/graphql/cart-item-input.md
@@ -0,0 +1,4 @@
+Attribute |  Data Type | Description
+--- | --- | ---
+`quantity` | Float! | The quantity of the item to add to the cart
+`sku` | String! | The sku of the product to be added to the cart
diff --git a/_includes/graphql/cart-object.md b/_includes/graphql/cart-object.md
@@ -0,0 +1,18 @@
+Attribute |  Data Type | Description
+--- | --- | ---
+`applied_coupon` | [`AppliedCoupon`][AppliedCoupon] | The `AppliedCoupon` object contains the `code` text attribute, which specifies the coupon code
+`available_payment_methods` | [AvailablePaymentMethod][AvailablePaymentMethod] | Available payment methods
+`billing_address` | [BillingCartAddress][BillingCartAddress] | Contains the billing address specified in the customer's cart
+`email` | String | The customer's email address
+`items` | [CartItemInterface][CartItemInterface] | Contains the items in the customer's cart
+`prices` | [CartPrices][CartPrices] | Contains subtotals and totals
+`selected_payment_method` | [SelectedPaymentMethod][SelectedPaymentMethod] | Selected payment method
+`shipping_addresses` | [ShippingCartAddress][ShippingCartAddress] | Contains one or more shipping addresses
+
+[AppliedCoupon]: {{page.baseurl}}/graphql/reference/quote.html#AppliedCoupon
+[AvailablePaymentMethod]: {{page.baseurl}}/graphql/reference/quote.html#AvailablePaymentMethod
+[BillingCartAddress]: {{page.baseurl}}/graphql/reference/quote.html#BillingCartAddress
+[CartItemInterface]: {{page.baseurl}}/graphql/reference/quote.html#CartItemInterface
+[CartPrices]: {{page.baseurl}}/graphql/reference/quote.html#CartPrices
+[SelectedPaymentMethod]: {{page.baseurl}}/graphql/reference/quote.html#SelectedPaymentMethod
+[ShippingCartAddress]: {{page.baseurl}}/graphql/reference/quote.html#ShippingCartAddress
diff --git a/_includes/graphql/customizable-option-input.md b/_includes/graphql/customizable-option-input.md
@@ -0,0 +1,4 @@
+Attribute |  Data Type | Description
+--- | --- | ---
+`id` | Int! | A unique ID assigned to the customizable option
+`value_string` | String! | A value assigned to the the customizable option
diff --git a/guides/v2.3/graphql/reference/configurable-product.md b/guides/v2.3/graphql/reference/configurable-product.md
@@ -720,7 +720,7 @@ Attribute | Type | Description
 
 
 ### Example usage
-The following example adds two black Teton Pullover Hoodies size extra-small to the specified shopping cart. The `cart_id` used in this example was [generated]({{ page.baseurl }}/graphql/reference/quote.html#createEmptyCart) by creating an empty cart.
+The following example adds two black Teton Pullover Hoodies size extra-small to the specified shopping cart. The `cart_id` used in this example was [generated]({{ page.baseurl }}/graphql/reference/quote-create-cart.html) by creating an empty cart.
 
 **Request**
 

diff --git a/guides/v2.3/graphql/reference/quote-add-simple-products.md b/guides/v2.3/graphql/reference/quote-add-simple-products.md
@@ -0,0 +1,195 @@
+---
+group: graphql
+title: addSimpleProductsToCart mutation
+---
+
+Simple products are physical products that do not have variations, such as color, size, or price. The `addSimpleProductsToCart` mutation allows you to add multiple simple products to the cart at the same time, but you cannot add other product types with this mutation. To add a simple product to a cart, you must provide the cart ID, the SKU, and the quantity. You can also optionally provide customizable options.
+
+{:.bs-callout .bs-callout-info}
+The mutation for [adding configurable products]({{page.baseurl}}/graphql/reference/configurable-product.html) is defined in the `ConfigurableProductGraphQl` module.
+
+## Syntax
+
+`mutation: {addSimpleProductsToCart(input: AddSimpleProductsToCartInput): {AddSimpleProductsToCartOutput}}`
+
+## Example usage
+
+These examples show the minimal payload and a payload that includes customizable options.
+
+### Add a simple product to a cart
+
+The following example adds a simple product to a cart. The response contains the entire contents of the customer's cart.
+
+**Request**
+
+```text
+mutation {
+  addSimpleProductsToCart(
+    input: {
+      cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG",
+      cart_items: [
+        {
+          data: {
+            quantity: 1
+            sku: "24-MB04"
+          }
+        }
+      ]
+    }
+  ) {
+    cart {
+      items {
+        id
+        product {
+          name
+          sku
+        }
+        quantity
+      }
+    }
+  }
+}
+```
+
+**Response**
+
+```json
+{
+  "data": {
+    "addSimpleProductsToCart": {
+      "cart": {
+        "items": [
+          {
+            "id": "13",
+            "product": {
+              "name": "Strive Shoulder Pack",
+              "sku": "24-MB04"
+            },
+            "quantity": 1
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Add a simple product with customizable options to a cart
+
+If a product has a customizable option, you can specify the option's value in the `addSimpleProductsToCart` request.
+
+**Request**
+
+``` text
+mutation {
+  addSimpleProductsToCart (input: {
+    cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG",
+    cart_items: {
+      data: {
+        sku: "simple"
+        quantity: 1
+      },
+      customizable_options: [
+        {
+          id: 121
+          value_string: "field value"
+        }
+      ]
+    }
+  }) {
+    cart {
+      items {
+        product {
+           name
+        }
+        quantity
+        ... on SimpleCartItem {
+          customizable_options {
+            label
+            values {
+              value
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Response**
+
+```text
+{
+  "data": {
+    "addSimpleProductsToCart": {
+      "cart": {
+        "items": [
+          {
+            "product": {
+              "name": "simple"
+            },
+            "quantity": 1,
+            "customizable_options": [
+              {
+                "label": "Field Option",
+                "values": [
+                  {
+                    "value": "field value"
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Input attributes
+
+The top-level `AddSimpleProductsToCartInput` object is listed first. All child objects are listed in alphabetical order.
+
+### AddSimpleProductsToCartInput object {#AddSimpleProductsToCartInput}
+
+The `AddSimpleProductsToCartInput` object must contain the following attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`cart_id` | String! | The unique ID that identifies the customer's cart
+`cart_items` | [SimpleProductCartItemInput!](#SimpleProductCartItemInput) | Contains the cart item IDs and quantity of each item
+
+### CartItemInput object {#CartItemInputSimple}
+
+The `CartItemInput` object must contain the following attributes:
+
+{% include graphql/customizable-option-input.md %}
+
+### CustomizableOptionInput object {#CustomizableOptionInputSimple}
+
+The `CustomizableOptionInput` object must contain the following attributes:
+
+{% include graphql/customizable-option-input.md %}
+
+### SimpleProductCartItemInput object {#SimpleProductCartItemInput}
+
+The `SimpleProductCartItemInput` object must contain the following attributes:
+
+`customizable_options` |[[CustomizableOptionInputSimple]](#CustomizableOptionInputSimple) | An array that defines customizable options for the product
+`data` | [CartItemInput!](#CartItemInputSimple) | An object containing the `sku` and `quantity` of the product.
+
+## Output attributes
+
+The `AddSimpleProductsToCartOutput` object contains the `Cart` object.
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart
+
+### Cart object {#CartObject}
+
+{% include graphql/cart-object.md %}
+
+[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object.