GraphQL mutations

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.

Anchor to Mutation structureMutation 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. 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 object. These are the pieces of data that you want the mutation to return. In GraphQL, you specify exactly what data you want returned.

Anchor to ExampleExample

Anchor to Input objectsInput 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 input object. The CustomerInput type defines all the fields that can be used to create or modify a customer.

Anchor to ExampleExample

Anchor to Return fieldsReturn 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 mutation is the Customer object that was created by a successful mutation. Like GraphQL 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.

Anchor to ExampleExample

Anchor to Example: Create a customerExample: Create a customer

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

Anchor to Next stepsNext steps

Learn how to write reusable requests using variables.