---
title: GraphQL mutations
description: Learn about GraphQL queries and follow some examples for modifying data.
source_url:
  html: 'https://shopify.dev/docs/apps/build/graphql/basics/mutations'
  md: 'https://shopify.dev/docs/apps/build/graphql/basics/mutations.md'
---

ExpandOn this page

* [Mutation structure](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#mutation-structure)
* [Input objects](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#input-objects)
* [Return fields](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#return-fields)
* [Example: Create a customer](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#example-create-a-customer)
* [Next steps](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#next-steps)

# GraphQL mutations

Note

The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate).

GraphQL mutations create and modify objects, similar to a `PUT`, `POST`, or `DELETE` request in REST. However, unlike REST, GraphQL mutations are sent to a single endpoint and use the `POST` HTTP method.

For a full list of available mutations, refer to the relevant API's reference.

***

## Mutation structure

GraphQL mutations have the following structure:

* The `mutation` operation name. This is the keyword that starts a mutation operation in a GraphQL request.
* The mutation field name, such as [`customerCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerCreate). This is the specific mutation to perform, as defined in the GraphQL schema.
* The input data to use in the mutation, such as the information for a new customer. This is the data that the mutation needs to perform its operation. It's passed as an argument to the mutation field.
* A selection of return fields that should be included in the response, such as the ID of a successfully created [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer) object. These are the pieces of data that you want the mutation to return. In GraphQL, you specify exactly what data you want returned.

### Example

## Mutation structure

```graphql
mutation {
  mutationName(arg: "Data") {
    return fields
  }
}
```

## Mutation structure with data

```graphql
mutation {
  customerCreate(input: { firstName: "Ayumu", lastName: "Hirano", email: "ayumu@example.com" }) {
    customer {
      id
    }
  }
}
```

***

## Input objects

Mutations require input data, such as the data to create a new object, or the ID of an object to delete. For mutations that might require a substantial data object, the schema provides a dedicated input object type.

For example, the [`customerCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerCreate) mutation requires an `input` argument, which accepts a [`CustomerInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/customerinput) input object. The `CustomerInput` type defines all the fields that can be used to create or modify a customer.

### Example

## Mutation input

```graphql
mutation {
  customerCreate(
    input: {
      firstName: "Ayumu",
      lastName: "Hirano",
      email: "ayumu@example.com"
    }
  )
  {
    ...
  }
}
```

***

## Return fields

Each mutation provides a set of fields that can be returned in the response. For example, one of the return fields that's available for the [`customerCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerCreate) mutation is the [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer) object that was created by a successful mutation. Like GraphQL [queries](https://shopify.dev/docs/apps/build/graphql/basics/queries), you can select the fields on the new object that you want to include in the response.

Each mutation can also return the `userErrors` field. The `userErrors` field returns information about errors when a mutation fails. You should include the `userErrors` field with each mutation to make it easier to troubleshoot failed mutations. Learn more about [error handling in GraphQL](https://shopify.dev/docs/apps/build/graphql/migrate/learn-how#understanding-error-handling).

### Example

## Mutation return fields

```graphql
mutation {
  customerCreate(
    input: {
      ...
    }
  )
  {
    customer {
      id
      displayName
    }
    userErrors {
      field
      message
    }
  }
}
```

***

## Example: Create a customer

The following mutation uses input objects and return fields to create a new customer and return their `id` and `displayName`:

## POST /admin/api/{api\_version}/graphql.json

## GraphQL mutation

```graphql
mutation {
  customerCreate(
    input: {
      firstName: "Ayumu",
      lastName: "Hirano",
      email: "ayumu@example.com"
    }
  )
  {
    customer {
      id
      displayName
    }
    userErrors {
      field
      message
    }
  }
}
```

## JSON response

```json
{
  "data": {
    "customerCreate": {
      "customer": {
        "id": "gid:\/\/shopify\/Customer\/1310036885526",
        "displayName": "Ayumu Hirano"
      },
      "userErrors": []
    }
  }
  ...
}
```

***

## Next steps

Learn how to write reusable requests using [variables](https://shopify.dev/docs/apps/build/graphql/basics/variables).

***

* [Mutation structure](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#mutation-structure)
* [Input objects](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#input-objects)
* [Return fields](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#return-fields)
* [Example: Create a customer](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#example-create-a-customer)
* [Next steps](https://shopify.dev/docs/apps/build/graphql/basics/mutations.md#next-steps)