magento/devdocs#7367: Added the article "addProductsToCart mutation"

src/_data/toc/graphql.yml

@@ -132,6 +132,10 @@ pages:
         - label: Using mutations
           url: /graphql/mutations/index.html
 
+        - label: addProductsToCart mutation
+          url: /graphql/mutations/add-products-to-cart.html
+          exclude_versions: ["2.3"]
+
         - label: addBundleProductsToCart mutation
           url: /graphql/mutations/add-bundle-products.html
 

src/_includes/graphql/entered-option-input.md

@@ -0,0 +1,4 @@
+Attribute |  Data Type | Description
+--- | --- | ---
+`uid` | ID! | An encoded ID
+`value` | String! | Text the customer entered

src/guides/v2.4/graphql/mutations/add-bundle-products.md

@@ -5,6 +5,9 @@ contributor_name: Atwix
 contributor_link: https://www.atwix.com/
 ---
 
+{:.bs-callout-warning}
+Magento recommends using the [addProductsToCart mutation]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) to add any type of product to the cart.
+
 Use the `addBundleProductsToCart` mutation to add bundle products to a specific cart.
 
 ## Syntax

src/guides/v2.4/graphql/mutations/add-configurable-products.md

@@ -3,6 +3,9 @@ group: graphql
 title: addConfigurableProductsToCart mutation
 ---
 
+{:.bs-callout-warning}
+Magento recommends using the [addProductsToCart mutation]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) to add any type of product to the cart.
+
 Use the `addConfigurableProductsToCart` mutation to add configurable products to a specific cart.
 
 ## Syntax

src/guides/v2.4/graphql/mutations/add-downloadable-products.md

@@ -5,6 +5,9 @@ contributor_name: Atwix
 contributor_link: https://www.atwix.com/
 ---
 
+{:.bs-callout-warning}
+Magento recommends using the [addProductsToCart mutation]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) to add any type of product to the cart.
+
 A downloadable product can be anything that you can deliver as a file, such as an eBook, music, video, software application, or an update. To add a downloadable product to a cart, you must provide the cart ID, the SKU, and the quantity. In some cases, you must include the IDs for downloadable product links. You can also optionally specify customizable options.
 
 ## Syntax

src/guides/v2.4/graphql/mutations/add-products-to-cart.md

@@ -0,0 +1,314 @@
+---
+group: graphql
+title: addProductsToCart mutation
+---
+
+Magento 2.4.1 introduced the `addProductsToCart` mutation that streamlines the process of adding the products to the shopping cart. It allows you to add a number of products to the cart at one time regardless of product types.
+
+You must specify the Cart ID along with the list of SKU and Quantity pairs as parameters to add the products to the shopping cart.
+
+## Syntax
+
+```graphql
+mutation {
+  addProductsToCart(
+    cartId: String
+    cartItems: [CartItemInput]
+  ) {
+    AddProductsToCartOutput
+  }
+}
+```
+
+## Example usage
+
+These examples show the minimal payload and a payload that includes customizable options.
+
+### Add a product to a cart
+
+The following example adds a product to a cart. The response contains the minimal payload contents of the customer's cart.
+
+**Request:**
+
+```graphql
+mutation {
+  addProductsToCart(
+    cartId: "HbpLADRmSo5h2dCdF85O5wCaVnrworKL"
+    cartItems: [
+      {
+        quantity: 1
+        sku: "24-MB04"
+      }
+    ]
+  ) {
+    cart {
+      items {
+        id
+        product {
+          name
+          sku
+        }
+        quantity
+      }
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "addProductsToCart": {
+      "cart": {
+        "items": [
+          {
+            "id": "346",
+            "product": {
+              "name": "Strive Shoulder Pack",
+              "sku": "24-MB04"
+            },
+            "quantity": 1
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Options
+
+Each product may have options. An option can be of 2 types.
+
+`selected_options` - predefined and selected by customer option. E.g. it can be customizable option: color: green, size: 28 or bundle option: Memory: 24M, Warranty: 1y, etc.
+
+Add a product with selected options to a cart.
+
+**Request:**
+
+```graphql
+mutation {
+  addProductsToCart(
+    cartId: "HbpLADRmSo5h2dCdF85O5wCaVnrworKL"
+    cartItems: [
+      {
+        quantity: 1
+        sku: "WSH12"
+        selected_options: ["Y29uZmlndXJhYmxlLzkzLzExNA==","Y29uZmlndXJhYmxlLzE5OS8yMzI="]
+      }
+    ]
+  ) {
+    cart {
+      items {
+        id
+        product {
+          name
+          sku
+        }
+        ... on ConfigurableCartItem {
+          configurable_options {
+            id
+            option_label
+            value_id
+            value_label
+          }
+        }
+        quantity
+      }
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "addProductsToCart": {
+      "cart": {
+        "items": [
+          {
+            "id": "348",
+            "product": {
+              "name": "Erika Running Short",
+              "sku": "WSH12"
+            },
+            "configurable_options": [
+              {
+                "id": 93,
+                "option_label": "Color",
+                "value_id": 114,
+                "value_label": "Green"
+              },
+              {
+                "id": 199,
+                "option_label": "Size",
+                "value_id": 232,
+                "value_label": "28"
+              }
+            ],
+            "quantity": 1
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+`entered_options` - option entered by a customer like: text field, image, etc.
+
+Add a product with entered options to a cart.
+
+**Request:**
+
+```graphql
+mutation {
+  addProductsToCart(
+    cartId: "HbpLADRmSo5h2dCdF85O5wCaVnrworKL"
+    cartItems: [
+      {
+        quantity: 1
+        sku: "24-WG03"
+        entered_options: [{
+          uid: "Y3VzdG9tLW9wdGlvbi81Mg=="
+          value: "Test Engraving"
+        }]
+      }
+    ]
+  ) {
+    cart {
+      items {
+        id
+        product {
+          name
+          sku
+        }
+        ... on SimpleCartItem {
+          customizable_options {
+            id
+            label
+            values {
+              id
+              value
+            }
+          }
+        }
+        quantity
+      }
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "addProductsToCart": {
+      "cart": {
+        "items": [
+          {
+            "id": "350",
+            "product": {
+              "name": "Clamber Watch",
+              "sku": "24-WG03"
+            },
+            "customizable_options": [
+              {
+                "id": 52,
+                "label": "Engraving",
+                "values": [
+                  {
+                    "id": 1184,
+                    "value": "Test Engraving"
+                  }
+                ]
+              }
+            ],
+            "quantity": 1
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+We can consider `selected_option` and `entered_option` as a unique identifier. They meet the criteria:
+
+-  `selected_option` represents option value, while `entered_option` represents an option
+
+-  Uid is unique across different options
+
+-  Uid must be returned from the server
+
+-  Used by the client as is (opaque)
+
+Selected options can be used for:
+
+-  Customizable options such a dropdown, radiobutton, checkbox, etc.
+
+-  Configurable product
+
+-  Bundle Product
+
+-  Downloadable product
+
+-  Grouped product
+
+-  Gift Card (amount)
+
+Entered options:
+
+-  Customizable options such as text field, file, etc.
+
+-  Gift Card (custom amount, sender fields, recipient fields, message)
+
+## Input attributes
+
+The `addProductsToCart` mutation must contain the following attributes:
+
+Attribute |  Data Type | Description
+--- | --- | ---
+`cartId` | String! | The unique ID that identifies the customer's cart
+`cartItems` | [[CartItemInput!]!](#CartItemInput) | Contains the cart item IDs and quantity of each item
+
+### CartItemInput object {#CartItemInput}
+
+The `CartItemInput` object must contain the following attributes:
+
+{% include graphql/cart-item-input.md %}
+
+### EnteredOptionInput object {#EnteredOptionInput}
+
+The `EnteredOptionInput` object must contain the following attributes:
+
+{% include graphql/entered-option-input.md %}
+
+## Output attributes
+
+The `AddProductsToCartOutput` 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/queries/cart.html#cart-output) provides more information about the `Cart` object.
+
+## Errors
+
+Code | Error | Description
+--- | --- | ---
+`PRODUCT_NOT_FOUND` | `Could not find a product with SKU "XXX"` | A product with the SKU specified in the argument `data`.`sku` does not exist.
+`NOT_SALABLE` | `Product that you are trying to add is not available.` | A requested product is not available
+`INSUFFICIENT_STOCK` | `This product is out of stock` | A requested product is out of stock
+`UNDEFINED` | `UNDEFINED` | An error message is not matched with any code

src/guides/v2.4/graphql/mutations/add-simple-products.md

@@ -5,6 +5,9 @@ redirect from:
   - /guides/v2.3/graphql/reference/quote-add-simple-products.html
 ---
 
+{:.bs-callout-warning}
+Magento recommends using the [addProductsToCart mutation]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) to add any type of product to the cart.
+
 The `addSimpleProductsToCart` mutation allows you to add any number of simple and group products to the cart at the same time.
 
 Simple products are physical products that do not have variations, such as color, size, or price. Group products are a set of simple standalone products that are assigned a unique SKU and are presented as a group. Each product in the group is purchased as a separate item.

src/guides/v2.4/graphql/mutations/add-virtual-products.md

@@ -5,6 +5,9 @@ redirect from:
   - /guides/v2.3/graphql/reference/quote-add-virtual-products.html
 ---
 
+{:.bs-callout-warning}
+Magento recommends using the [addProductsToCart mutation]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) to add any type of product to the cart.
+
 A virtual product represents a saleable item that is not physical, such as a membership, service, warranty, or subscription. Virtual products do not need to be shipped or downloaded, nor do they require stock management.
 
 The `addVirtualProductsToCart` mutation allows you to add multiple virtual products to the cart at the same time, but you cannot add other product types with this mutation. To add a virtual product to a cart, you must provide the cart ID, the SKU, and the quantity. You can also optionally provide customizable options.