Mutations

This is part 3 of the series for GraphQL and Adobe Commerce. Mutations are the ability to save, update, and return values using GraphQL.

Related videos and tutorials on GraphQL in this series

Example mutation

Any complete API specification needs to offer the ability not only to query data, but also to create and update it.

REST distinguishes between requests that change data and those that do not with the request type or “verb” (GET vs. POST or PUT).
When using GraphQL, data-modifying queries are distinguished by the mutation keyword that corresponds with a different
root type in the schema defined at the server.

Look at this example mutation for adding a product to a user’s cart. (This requires a cart ID that was generated
for the logged-in customer’s session or using the createEmptyCart mutation.)

mutation doAddToCart(
    $cartId: String!,
    $cartItems: [CartItemInput!]!
) {
    addProductsToCart(
        cartId: $cartId
        cartItems: $cartItems
    ) {
        cart {
            total_quantity
            prices {
                grand_total {
                    value
                }
            }
        }
    }
}

You can imagine the above mutation being sent in a request along with the following variables dictionary:

{
  "cartId": "{cart-id}",
  "cartItems": [
    {
      "quantity": 1,
      "sku": "VT01-RN-XS"
    }
  ]
}

And finally, you might receive a response like this:

{
  "data": {
    "addProductsToCart": {
      "cart": {
        "total_quantity": 1,
        "prices": {
          "grand_total": {
            "value": 35.2
          }
        }
      }
    }
  }
}

The chief thing to note that about the above example is that, apart from the use of the mutation keyword instead of query,
the syntax is identical to a query. Like queries, the mutation includes:

The fields subselection allows you to flexibly define the fields you would like returned (from the type assigned as the
return value of addProductsToCart - AddProductsToCartOutput) after the mutation is completed.

As explained previously, fields defined in a GraphQL schema start on a root type for queries (typically referred to as a Query). Similarly,
another root type exists for mutations (typically referred to as Mutation). addProductsToCart is a field
on that root type.

A few other notes about the above example:

Useful GraphQL resources