Using Input Types in Custom GraphQL Mutations in Magento 2

Creating custom GraphQL mutations in Magento 2 is a powerful way to expose backend functionality through your API. But to make your mutations clean, scalable, and reusable — especially when handling multiple fields — using Input Types is the way to go.

In this post, we’ll explain what Input Types are, why they matter, and how to use them effectively in your Magento 2 custom GraphQL mutations.

🤔 What are Input Types in GraphQL?

In GraphQL, Input Types are special object types used only as arguments for mutations or queries. They help you bundle multiple fields together instead of passing them separately — making your APIs cleaner and easier to maintain.

Example without Input Type:

mutation {
  createRecord(title: "Test", description: "Some text", status: true) {
    id
  }
}

Example with Input Type:

mutation {
  createRecord(input: {
    title: "Test",
    description: "Some text",
    status: true
  }) {
    id
  }
}

Much cleaner, right?

✅ Why Use Input Types in Magento 2?

Magento 2 encourages using Input Types in custom GraphQL mutations because:

• ✅ Scalability: Add more fields without changing the mutation signature.
• ✅ Validation Friendly: Easier to validate complex input data.
• ✅ Reusability: Share the input type across multiple mutations if needed.
• ✅ Consistency: Aligns with Magento’s GraphQL schema design best practices.

🛠️ How to Use Input Types in Magento 2 GraphQL Mutations

Let’s break it down step-by-step with an example.

1. Define Your Input Type in schema.graphqls

Create your module’s etc/schema.graphqls file:

input CustomRecordInput {
  title: String!
  description: String
  status: Boolean
}

type Mutation {
  createRecord(input: CustomRecordInput!): CustomRecordOutput
}

2. Create a Resolver

Your resolver will receive the input array as an argument:

public function resolve(
    Field $field,
    $context,
    ResolveInfo $info,
    array $value = null,
    array $args = null
) {
    $input = $args['input'];
    
    $title = $input['title'];
    $description = $input['description'] ?? '';
    $status = $input['status'] ?? false;

    // Custom logic here...

    return [
        'id' => 1,
        'title' => $title,
        'description' => $description,
        'status' => $status
    ];
}

3. Add Your Output Type

type CustomRecordOutput {
  id: Int
  title: String
  description: String
  status: Boolean
}

🧪 Example Mutation in Postman

Use this in your GraphQL tab in Postman:

{
  "query": "mutation Create($input: CustomRecordInput!) { createRecord(input: $input) { id title description status } }",
  "variables": {
    "input": {
      "title": "Learn GraphQL",
      "description": "From Magento GraphQL series",
      "status": true
    }
  }
}

🎯 Pro Tips: Using Input Types in Custom GraphQL Mutations in Magento 2

• Always mark required fields with ! in the GraphQL schema.
• Validate the $args['input'] fields in your resolver to prevent issues.
• Keep your input and output types separate — don’t reuse the same type for both!

🚀 Final Thoughts

Using Input Types is a clean and scalable way to structure your Magento 2 GraphQL mutations. It simplifies the API, keeps the schema organized, and provides flexibility for future growth.

Keep experimenting and growing your Magento GraphQL skills! 🚀

Stay connected with SB Dev Blog for more Magento development tutorials.