Merge pull request #7662 from magento/kh_rewards-mutations

GraphQL: Add mutations for applying/removing reward points

Author: keharper

src/_data/toc/graphql.yml

@@ -147,12 +147,17 @@ pages:
         - label: addVirtualProductsToCart mutation
           url: /graphql/mutations/add-virtual-products.html
 
+        - label: applyCouponToCart mutation
+          url: /graphql/mutations/apply-coupon.html
+
         - label: applyGiftCardToCart mutation
           url: /graphql/mutations/apply-giftcard.html
           edition: ee-only
 
-        - label: applyCouponToCart mutation
-          url: /graphql/mutations/apply-coupon.html
+        - label: applyRewardPointsToCart mutation
+          url: /graphql/mutations/apply-reward-points.html
+          edition: ee-only
+          exclude_versions: ["2.3"]
 
         - label: applyStoreCreditToCart mutation
           url: /graphql/mutations/apply-store-credit.html
@@ -211,6 +216,11 @@ pages:
         - label: removeItemFromCart mutation
           url: /graphql/mutations/remove-item.html
 
+        - label: removeRewardPointsFromCart mutation
+          url: /graphql/mutations/remove-reward-points.html
+          edition: ee-only
+          exclude_versions: ["2.3"]
+
         - label: removeStoreCreditFromCart mutation
           url: /graphql/mutations/remove-store-credit.html
           edition: ee-only

src/guides/v2.4/graphql/mutations/apply-reward-points.md

@@ -0,0 +1,136 @@
+---
+group: graphql
+title: applyRewardPointsToCart mutation
+ee_only: True
+---
+
+The `applyRewardPointsToCart` mutation applies reward points to the customer's cart. You cannot specify a quantity of reward points. If the reward points balance is less than the cart total, Magento applies the entire reward points balance. Otherwise, Magento applies as many reward points needed to bring the total to 0. Fractional reward points are discarded.
+
+Use the [`removeRewardPointsFromCart` mutation]({{page.baseurl}}/graphql/mutations/remove-reward-points.html) to undo the results of the `applyRewardPointsToCart` mutation.
+
+## Syntax
+
+`mutation: applyRewardPointsToCart(cartId: ID!): ApplyRewardPointsToCartOutput`
+
+## Example usage
+
+The following example applies $5 to the cart. In this example, the exchange rate is defined as 25 reward points equals $5.
+
+**Request:**
+
+```graphql
+mutation {
+  applyRewardPointsToCart(cartId: "8k0Q4MpH2IGahWrTRtqM61YV2MtLPApz")
+  {
+    cart {
+      items {
+        quantity
+        product {
+          sku
+          name
+          price_range {
+            maximum_price {
+              final_price {
+                currency
+                value
+              }
+            }
+          }
+        }
+      }
+      applied_reward_points {
+        money {
+          currency
+          value
+        }
+        points
+      }
+      prices {
+        grand_total {
+          currency
+          value
+        }
+        applied_taxes {
+          amount {
+            currency
+            value
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "applyRewardPointsToCart": {
+      "cart": {
+        "items": [
+          {
+            "quantity": 1,
+            "product": {
+              "sku": "WJ04",
+              "name": "Ingrid Running Jacket",
+              "price_range": {
+                "maximum_price": {
+                  "final_price": {
+                    "currency": "USD",
+                    "value": 84
+                  }
+                }
+              }
+            }
+          }
+        ],
+        "applied_reward_points": {
+          "money": {
+            "currency": "USD",
+            "value": 5
+          },
+          "points": 25
+        },
+        "prices": {
+          "grand_total": {
+            "currency": "USD",
+            "value": 90.93
+          },
+          "applied_taxes": [
+            {
+              "amount": {
+                "currency": "USD",
+                "value": 6.93
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## Input attributes
+
+The `applyRewardPointsToCart` mutation requires the `cart_id` attribute.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`cart_id` | String! | The unique ID that identifies the customer's cart
+
+## Output attributes
+
+The `ApplyRewardPointsToCartOutput` 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-24.md %}
+
+[Cart query output]({{page.baseurl}}/graphql/queries/cart.html#cart-output) provides more information about the `Cart` object.

src/guides/v2.4/graphql/mutations/remove-reward-points.md

@@ -0,0 +1,96 @@
+---
+group: graphql
+title: removeRewardPointsFromCart mutation
+ee_only: True
+---
+
+The `removeRewardPointsFromCart` mutation removes all reward points that were previously applied to the customer's cart with the [`applyRewardPointsToCart` mutation]({{page.baseurl}}/graphql/mutations/apply-reward-points.html).
+
+## Syntax
+
+`mutation: removeRewardPointsFromCart(cartId: ID!): RemoveRewardPointsFromCartOutput`
+
+## Example usage
+
+The following example removes all reward points from the customer's cart. The `applied_rewards_points` object is now null.
+
+**Request:**
+
+```graphql
+mutation {
+  removeRewardPointsFromCart(cartId: "8k0Q4MpH2IGahWrTRtqM61YV2MtLPApz")
+  {
+    cart {
+      applied_reward_points {
+        money {
+          currency
+          value
+        }
+        points
+      }
+      prices {
+        applied_taxes {
+          amount {
+            currency
+            value
+          }
+        }
+        grand_total {
+          currency
+          value
+        }
+      }
+    }
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "data": {
+    "removeRewardPointsFromCart": {
+      "cart": {
+        "applied_reward_points": null,
+        "prices": {
+          "applied_taxes": [
+            {
+              "amount": {
+                "currency": "USD",
+                "value": 6.93
+              }
+            }
+          ],
+          "grand_total": {
+            "currency": "USD",
+            "value": 90.93
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Input attributes
+
+The `removeRewardPointsFromCart` mutation requires the `cart_id` attribute.
+
+Attribute | Data Type | Description
+--- | --- | ---
+`cart_id` | String! | The unique ID that identifies the customer's cart
+
+## Output attributes
+
+The `RemoveRewardPointsFromCartOutput` 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-24.md %}
+
+[Cart query output]({{page.baseurl}}/graphql/queries/cart.html#cart-output) provides more information about the `Cart` object.