# metaobjectDefinitionCreate - admin-graphql - MUTATION
Version: 2025-01

## Description
Creates a new metaobject definition.

### Access Scopes
`write_metaobject_definitions` access scope.


## Arguments
* [definition](/docs/api/admin-graphql/2025-01/input-objects/MetaobjectDefinitionCreateInput): MetaobjectDefinitionCreateInput! - The input fields for creating a metaobject definition.


## Returns
* [metaobjectDefinition](/docs/api/admin-graphql/2025-01/objects/MetaobjectDefinition): MetaobjectDefinition The created metaobject definition.
* [userErrors](/docs/api/admin-graphql/2025-01/objects/MetaobjectUserError): 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" 
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}"
#### Graphql 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})$"
          }
        ]
      }
    ]
  }
}
#### Graphql 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" 
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}"
#### Graphql 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"
          }
        ]
      }
    ]
  }
}
#### Graphql 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" 
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}"
#### Graphql 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"
          }
        ]
      }
    ]
  }
}
#### Graphql 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": []
    }
  }
}