metaobjectDefinitionCreate - admin-graphql - MUTATION

Version: 2025-01

Description:

Creates a new metaobject definition.

Access Scopes

`write_metaobject_definitions` access scope.

Arguments

• definition: MetaobjectDefinitionCreateInput! - The input fields for creating a metaobject definition.

Returns

• metaobjectDefinition: MetaobjectDefinition The created metaobject definition.
• userErrors: MetaobjectUserError! The list of errors that occurred from executing the mutation.

Examples

• Create a metaobject definition

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) { metaobjectDefinitionCreate(definition: $definition) { metaobjectDefinition { name type fieldDefinitions { name key } } userErrors { field message code } } }\",\n \"variables\": {\n    \"definition\": {\n      \"name\": \"Color swatch\",\n      \"type\": \"color-swatch\",\n      \"fieldDefinitions\": [\n        {\n          \"name\": \"Hex\",\n          \"key\": \"hex\",\n          \"type\": \"single_line_text_field\",\n          \"validations\": [\n            {\n              \"name\": \"regex\",\n              \"value\": \"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n      metaobjectDefinitionCreate(definition: $definition) {\n        metaobjectDefinition {\n          name\n          type\n          fieldDefinitions {\n            name\n            key\n          }\n        }\n        userErrors {\n          field\n          message\n          code\n        }\n      }\n    }`,\n    \"variables\": {\n      \"definition\": {\n        \"name\": \"Color swatch\",\n        \"type\": \"color-swatch\",\n        \"fieldDefinitions\": [\n          {\n            \"name\": \"Hex\",\n            \"key\": \"hex\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"regex\",\n                \"value\": \"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$\"\n              }\n            ]\n          }\n        ]\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"definition\": {\n    \"name\": \"Color swatch\",\n    \"type\": \"color-swatch\",\n    \"fieldDefinitions\": [{\"name\"=>\"Hex\", \"key\"=>\"hex\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"regex\", \"value\"=>\"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$\"}]}]\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"definition\" => [\n    \"name\" => \"Color swatch\",\n    \"type\" => \"color-swatch\",\n    \"fieldDefinitions\" => [{\"name\"=>\"Hex\", \"key\"=>\"hex\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"regex\", \"value\"=>\"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$\"}]}],\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"definition\": {\n        \"name\": \"Color swatch\",\n        \"type\": \"color-swatch\",\n        \"fieldDefinitions\": [\n          {\n            \"name\": \"Hex\",\n            \"key\": \"hex\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"regex\",\n                \"value\": \"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$\"\n              }\n            ]\n          }\n        ]\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n  metaobjectDefinitionCreate(definition: $definition) {\n    metaobjectDefinition {\n      name\n      type\n      fieldDefinitions {\n        name\n        key\n      }\n    }\n    userErrors {\n      field\n      message\n      code\n    }\n  }\n}"
        

  input: {
    "definition": {
      "name": "Color swatch",
      "type": "color-swatch",
      "fieldDefinitions": [
        {
          "name": "Hex",
          "key": "hex",
          "type": "single_line_text_field",
          "validations": [
            {
              "name": "regex",
              "value": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
            }
          ]
        }
      ]
    }
  }

  response: {
    "data": {
      "metaobjectDefinitionCreate": {
        "metaobjectDefinition": {
          "name": "Color swatch",
          "type": "color-swatch",
          "fieldDefinitions": [
            {
              "name": "Hex",
              "key": "hex"
            }
          ]
        },
        "userErrors": []
      }
    }
  }

  Create a metaobject definition with custom access controls

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) { metaobjectDefinitionCreate(definition: $definition) { metaobjectDefinition { name type access { admin storefront } fieldDefinitions { name key } } userErrors { field message code } } }\",\n \"variables\": {\n    \"definition\": {\n      \"name\": \"FAQ\",\n      \"type\": \"$app:faq\",\n      \"access\": {\n        \"admin\": \"MERCHANT_READ_WRITE\",\n        \"storefront\": \"PUBLIC_READ\"\n      },\n      \"fieldDefinitions\": [\n        {\n          \"name\": \"Question\",\n          \"key\": \"question\",\n          \"type\": \"single_line_text_field\",\n          \"validations\": [\n            {\n              \"name\": \"max\",\n              \"value\": \"100\"\n            }\n          ]\n        },\n        {\n          \"name\": \"Answer\",\n          \"key\": \"answer\",\n          \"type\": \"multi_line_text_field\",\n          \"validations\": [\n            {\n              \"name\": \"max\",\n              \"value\": \"250\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n      metaobjectDefinitionCreate(definition: $definition) {\n        metaobjectDefinition {\n          name\n          type\n          access {\n            admin\n            storefront\n          }\n          fieldDefinitions {\n            name\n            key\n          }\n        }\n        userErrors {\n          field\n          message\n          code\n        }\n      }\n    }`,\n    \"variables\": {\n      \"definition\": {\n        \"name\": \"FAQ\",\n        \"type\": \"$app:faq\",\n        \"access\": {\n          \"admin\": \"MERCHANT_READ_WRITE\",\n          \"storefront\": \"PUBLIC_READ\"\n        },\n        \"fieldDefinitions\": [\n          {\n            \"name\": \"Question\",\n            \"key\": \"question\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"100\"\n              }\n            ]\n          },\n          {\n            \"name\": \"Answer\",\n            \"key\": \"answer\",\n            \"type\": \"multi_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"250\"\n              }\n            ]\n          }\n        ]\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        access {\n          admin\n          storefront\n        }\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"definition\": {\n    \"name\": \"FAQ\",\n    \"type\": \"$app:faq\",\n    \"access\": {\n      \"admin\": \"MERCHANT_READ_WRITE\",\n      \"storefront\": \"PUBLIC_READ\"\n    },\n    \"fieldDefinitions\": [{\"name\"=>\"Question\", \"key\"=>\"question\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"100\"}]}, {\"name\"=>\"Answer\", \"key\"=>\"answer\", \"type\"=>\"multi_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"250\"}]}]\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        access {\n          admin\n          storefront\n        }\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"definition\" => [\n    \"name\" => \"FAQ\",\n    \"type\" => \"$app:faq\",\n    \"access\" => [\n      \"admin\" => \"MERCHANT_READ_WRITE\",\n      \"storefront\" => \"PUBLIC_READ\",\n    ],\n    \"fieldDefinitions\" => [{\"name\"=>\"Question\", \"key\"=>\"question\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"100\"}]}, {\"name\"=>\"Answer\", \"key\"=>\"answer\", \"type\"=>\"multi_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"250\"}]}],\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        access {\n          admin\n          storefront\n        }\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"definition\": {\n        \"name\": \"FAQ\",\n        \"type\": \"$app:faq\",\n        \"access\": {\n          \"admin\": \"MERCHANT_READ_WRITE\",\n          \"storefront\": \"PUBLIC_READ\"\n        },\n        \"fieldDefinitions\": [\n          {\n            \"name\": \"Question\",\n            \"key\": \"question\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"100\"\n              }\n            ]\n          },\n          {\n            \"name\": \"Answer\",\n            \"key\": \"answer\",\n            \"type\": \"multi_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"250\"\n              }\n            ]\n          }\n        ]\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n  metaobjectDefinitionCreate(definition: $definition) {\n    metaobjectDefinition {\n      name\n      type\n      access {\n        admin\n        storefront\n      }\n      fieldDefinitions {\n        name\n        key\n      }\n    }\n    userErrors {\n      field\n      message\n      code\n    }\n  }\n}"
        

  input: {
    "definition": {
      "name": "FAQ",
      "type": "$app:faq",
      "access": {
        "admin": "MERCHANT_READ_WRITE",
        "storefront": "PUBLIC_READ"
      },
      "fieldDefinitions": [
        {
          "name": "Question",
          "key": "question",
          "type": "single_line_text_field",
          "validations": [
            {
              "name": "max",
              "value": "100"
            }
          ]
        },
        {
          "name": "Answer",
          "key": "answer",
          "type": "multi_line_text_field",
          "validations": [
            {
              "name": "max",
              "value": "250"
            }
          ]
        }
      ]
    }
  }

  response: {
    "data": {
      "metaobjectDefinitionCreate": {
        "metaobjectDefinition": {
          "name": "FAQ",
          "type": "app--1830279--faq",
          "access": {
            "admin": "MERCHANT_READ_WRITE",
            "storefront": "PUBLIC_READ"
          },
          "fieldDefinitions": [
            {
              "name": "Question",
              "key": "question"
            },
            {
              "name": "Answer",
              "key": "answer"
            }
          ]
        },
        "userErrors": []
      }
    }
  }

  Create a metaobject definition with the publishable capability enabled

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) { metaobjectDefinitionCreate(definition: $definition) { metaobjectDefinition { name type capabilities { publishable { enabled } } fieldDefinitions { name key } } userErrors { field message code } } }\",\n \"variables\": {\n    \"definition\": {\n      \"name\": \"Custom Page\",\n      \"type\": \"$app:custom-page\",\n      \"capabilities\": {\n        \"publishable\": {\n          \"enabled\": true\n        }\n      },\n      \"fieldDefinitions\": [\n        {\n          \"name\": \"Title\",\n          \"key\": \"title\",\n          \"type\": \"single_line_text_field\",\n          \"validations\": [\n            {\n              \"name\": \"max\",\n              \"value\": \"100\"\n            }\n          ]\n        },\n        {\n          \"name\": \"Author\",\n          \"key\": \"author\",\n          \"type\": \"single_line_text_field\",\n          \"validations\": [\n            {\n              \"name\": \"max\",\n              \"value\": \"32\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n      metaobjectDefinitionCreate(definition: $definition) {\n        metaobjectDefinition {\n          name\n          type\n          capabilities {\n            publishable {\n              enabled\n            }\n          }\n          fieldDefinitions {\n            name\n            key\n          }\n        }\n        userErrors {\n          field\n          message\n          code\n        }\n      }\n    }`,\n    \"variables\": {\n      \"definition\": {\n        \"name\": \"Custom Page\",\n        \"type\": \"$app:custom-page\",\n        \"capabilities\": {\n          \"publishable\": {\n            \"enabled\": true\n          }\n        },\n        \"fieldDefinitions\": [\n          {\n            \"name\": \"Title\",\n            \"key\": \"title\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"100\"\n              }\n            ]\n          },\n          {\n            \"name\": \"Author\",\n            \"key\": \"author\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"32\"\n              }\n            ]\n          }\n        ]\n      }\n    },\n  },\n});\n"
          Ruby example: "session = ShopifyAPI::Auth::Session.new(\n  shop: \"your-development-store.myshopify.com\",\n  access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n  session: session\n)\n\nquery = <<~QUERY\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        capabilities {\n          publishable {\n            enabled\n          }\n        }\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"definition\": {\n    \"name\": \"Custom Page\",\n    \"type\": \"$app:custom-page\",\n    \"capabilities\": {\n      \"publishable\": {\n        \"enabled\": true\n      }\n    },\n    \"fieldDefinitions\": [{\"name\"=>\"Title\", \"key\"=>\"title\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"100\"}]}, {\"name\"=>\"Author\", \"key\"=>\"author\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"32\"}]}]\n  }\n}\n\nresponse = client.query(query: query, variables: variables)\n"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        capabilities {\n          publishable {\n            enabled\n          }\n        }\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"definition\" => [\n    \"name\" => \"Custom Page\",\n    \"type\" => \"$app:custom-page\",\n    \"capabilities\" => [\n      \"publishable\" => [\n        \"enabled\" => true,\n      ],\n    ],\n    \"fieldDefinitions\" => [{\"name\"=>\"Title\", \"key\"=>\"title\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"100\"}]}, {\"name\"=>\"Author\", \"key\"=>\"author\", \"type\"=>\"single_line_text_field\", \"validations\"=>[{\"name\"=>\"max\", \"value\"=>\"32\"}]}],\n  ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n"
          Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n  `#graphql\n  mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n    metaobjectDefinitionCreate(definition: $definition) {\n      metaobjectDefinition {\n        name\n        type\n        capabilities {\n          publishable {\n            enabled\n          }\n        }\n        fieldDefinitions {\n          name\n          key\n        }\n      }\n      userErrors {\n        field\n        message\n        code\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"definition\": {\n        \"name\": \"Custom Page\",\n        \"type\": \"$app:custom-page\",\n        \"capabilities\": {\n          \"publishable\": {\n            \"enabled\": true\n          }\n        },\n        \"fieldDefinitions\": [\n          {\n            \"name\": \"Title\",\n            \"key\": \"title\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"100\"\n              }\n            ]\n          },\n          {\n            \"name\": \"Author\",\n            \"key\": \"author\",\n            \"type\": \"single_line_text_field\",\n            \"validations\": [\n              {\n                \"name\": \"max\",\n                \"value\": \"32\"\n              }\n            ]\n          }\n        ]\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation CreateMetaobjectDefinition($definition: MetaobjectDefinitionCreateInput!) {\n  metaobjectDefinitionCreate(definition: $definition) {\n    metaobjectDefinition {\n      name\n      type\n      capabilities {\n        publishable {\n          enabled\n        }\n      }\n      fieldDefinitions {\n        name\n        key\n      }\n    }\n    userErrors {\n      field\n      message\n      code\n    }\n  }\n}"
        

  input: {
    "definition": {
      "name": "Custom Page",
      "type": "$app:custom-page",
      "capabilities": {
        "publishable": {
          "enabled": true
        }
      },
      "fieldDefinitions": [
        {
          "name": "Title",
          "key": "title",
          "type": "single_line_text_field",
          "validations": [
            {
              "name": "max",
              "value": "100"
            }
          ]
        },
        {
          "name": "Author",
          "key": "author",
          "type": "single_line_text_field",
          "validations": [
            {
              "name": "max",
              "value": "32"
            }
          ]
        }
      ]
    }
  }

  response: {
    "data": {
      "metaobjectDefinitionCreate": {
        "metaobjectDefinition": {
          "name": "Custom Page",
          "type": "app--1830279--custom-page",
          "capabilities": {
            "publishable": {
              "enabled": true
            }
          },
          "fieldDefinitions": [
            {
              "name": "Title",
              "key": "title"
            },
            {
              "name": "Author",
              "key": "author"
            }
          ]
        },
        "userErrors": []
      }
    }
  }