GraphQL mutations
GraphQL mutations create and modify objects, similar to a PUT, POST, or DELETE request in REST. Mutation requests are sent to the same endpoint as query requests.
For a full list of available mutations, see the GraphQL Admin API reference and the Storefront API reference.
Mutation structure
Mutations have the following structure:
- The
mutation
operation name - The mutation field name, such as
customerCreate
- The input data to use in the mutation passed as an argument, such as the information for a new customer
- A selection of return fields that should be included in the response, such as the ID of the successfully created Customer object
Mutation structure
mutation {
mutationName(arg: "Data") {
return fields
}
}
Mutation example
mutation {
customerCreate(input: { firstName: "John", lastName: "Tate", email: "john@johns-apparel.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
mutation requires an input
argument, which accepts a CustomerInput object. The CustomerInput type defines all the fields that can be used to create or modify a customer.
mutation {
customerCreate(
input: {
firstName: "Greg",
lastName: "Piotrowski",
email: "gregjpiotrowski@teleworm.us"
}
)
{
...
}
}
Return fields
Each mutation provides a set of fields that can be returned in the response. For example, one of the return fields available for the customerCreate mutation is the Customer object that was created by a successful mutation. As with a GraphQL query, you can select the fields on the new object that you want to include in the response.
Each mutation also returns 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.
mutation {
customerCreate(
input: {
...
}
)
{
customer {
id
displayName
}
userErrors {
field
message
}
}
}
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/2021-04/graphql.json
mutation {
customerCreate(
input: {
firstName: "Greg",
lastName: "Piotrowski",
email: "gregjpiotrowski@teleworm.us"
}
)
{
customer {
id
displayName
}
userErrors {
field
message
}
}
}
JSON response
{
"data": {
"customerCreate": {
"customer": {
"id": "gid:\/\/shopify\/Customer\/1310036885526",
"displayName": "Greg Piotrowski"
},
"userErrors": []
}
}
...
}
Next steps
- GraphQL variables - Learn how to simplify and re-use graphql requests through variables.