Create a Custom GraphQL Mutation in Magento2

Create a Custom GraphQL Mutation in Magento2 (Step-by-Step Guide). Magento 2’s support for GraphQL has opened up incredible possibilities for developers building fast, interactive frontends. While queries are great for fetching data, mutations are what you need when you want to change or insert data into your Magento database.

In this guide, we’ll walk you through how to create a custom GraphQL mutation in Magento 2 to perform insert/update operations into a custom table — a perfect step for building admin panels, customer forms, or integrations.

Create a Custom GraphQL Mutation in Magento2 (Step-by-Step Guide)

✨ What is a Mutation in GraphQL?

A mutation is like a POST, PUT, or DELETE request in REST. It’s used to send data to the server and change state — such as creating a new customer record or updating product details.

In Magento 2, mutations are defined in your module’s schema and handled by a resolver class.

🧱 Step-by-Step: Creating a Custom GraphQL Mutation

Let’s say you’ve already created a custom table named sbdevblog_custom_record. Now you want to insert records into it using GraphQL.

✅ Step 1: Define the Mutation in schema.graphqls

Create this file at:

app/code/SbDevBlog/CustomGraphQL/etc/schema.graphqls

Add:

input CustomerInput {
    id: Int
    first_name: String!
    last_name: String!
}

type Customer {
    id: Int
    first_name: String
    last_name: String
}

type CustomResponse {
    message: String
    input: Customer
}

type Mutation {
    createRecord(input: CustomerInput!): CustomResponse 
        @resolver(class: "SbDevBlog\\CustomMutation\\Model\\Resolver\\Mutation\\CreateRecord")
}

✅ Step 2: Create Resolver Class

Path:

app/code/SbDevBlog/CustomGraphQL/Model/Resolver/Mutation/CreateRecord.php

Example:

<?php
namespace SbDevBlog\CustomMutation\Model\Resolver\Mutation;

use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;

class CreateRecord implements ResolverInterface
{
    public function resolve(
        Field $field,
        $context,
        ResolveInfo $info,
        array $value = null,
        array $args = null
    ) {
        return [
            'message' => 'Mutation executed successfully!',
            'input' => $args['input']
        ];
    }
}

🚀 Testing the Mutation in Postman

Set POST URL to:

https://yourdomain.com/graphql

Add the following JSON payload:

{
  "query": "mutation createRecord($input: CustomerInput!) { createRecord(input: $input) { message input { first_name last_name } } }",
  "variables": {
    "input": {
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Set Content-Type to application/json. You should get a successful response.

🔧 Common Issues

• Schema not recognized? Make sure schema.graphqls is placed inside etc/ (not etc/graphql).
• Class not found? Double-check namespaces and autoload using setup:upgrade && di:compile.

🎯 Conclusion

Creating a custom GraphQL mutation in Magento 2 allows you to unlock the power of dynamic user inputs and data operations — ideal for modern apps, admin tools, and mobile apps.

In our next post, we’ll go even deeper: how to create mutations for updating and deleting records, and how to secure them.

Stay tuned to SB Dev Blog for more Magento GraphQL tutorials from beginner to advanced levels.