Mutations

The root Mutation type in a GraphQL schema defines all the write operations that can change data. It is analogous to performing HTTP verbs such as POST, PATCH, and DELETE.

Mutations can take arguments as input similar to the body of a POST request in REST. Like GraphQL queries, mutations can also return fields. This can be useful for fetching the new state of an object after an update.

The return type of mutations in the Storefront API always includes a userErrors field. This is a list of errors that occurred during the mutation and each error includes a message and field. These errors make it easy to display information to the user such as validation errors.

We strongly recommend to always include userErrors in your mutation query. If your mutation is returning null, it's likely that there are errors which you won't see without it.

Here's an example of a mutation and its errors:

mutation {
  customerCreate(input: {
    email: "user@example",
    password: "2r7yS#afhi2$@Fd7f24fjkdfs"
  }) {
    userErrors {
      field
      message
    }
    customer {
      id
    }
  }
}

{
  "data": {
    "customerCreate": {
      "userErrors": [
        {
          "field": [
            "email"
          ],
          "message": "Email is invalid"
        }
      ],
      "customer": null
    }
  }
}

Note

fieldis an array of field names that acts as a hierarchical path.

A successful mutation without errors would return the following:

{
  "data": {
    "customerCreate": {
      "userErrors": [],
      "customer": {
        "id": "Z2lkOi8vc2hvcGlmeS9DdXN0b21lci8x"
      }
    }
  }
}