metafieldDefinitionCreate

mutation

Requires API client to have access to the namespace and the resource type associated with the metafield definition.

Creates a metafield definition. Any metafields existing under the same owner type, namespace, and key will be checked against this definition and will have their type updated accordingly. For metafields that are not valid, they will remain unchanged but any attempts to update them must align with this definition.

Arguments

Anchor to definitiondefinition • MetafieldDefinitionInput!required: Specifies the input fields for a metafield definition.

Was this section helpful?

Anchor to MetafieldDefinitionCreatePayload returnsMetafieldDefinitionCreatePayload returns

Anchor to createdDefinitioncreatedDefinition • MetafieldDefinition: The metafield definition that was created.
Anchor to userErrorsuserErrors • [MetafieldDefinitionCreateUserError!]!non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

1const { admin } = await authenticate.admin(request);
2
3const response = await admin.graphql(
4  `#graphql
5  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
6    metafieldDefinitionCreate(definition: $definition) {
7      createdDefinition {
8        id
9        name
10      }
11      userErrors {
12        field
13        message
14        code
15      }
16    }
17  }`,
18  {
19    variables: {
20      "definition": {
21        "name": "Ingredients",
22        "namespace": "bakery",
23        "key": "ingredients",
24        "description": "A list of ingredients used to make the product.",
25        "type": "multi_line_text_field",
26        "ownerType": "PRODUCT"
27      }
28    },
29  },
30);
31
32const data = await response.json();
33

mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      name
    }
    userErrors {
      field
      message
      code
    }
  }
}

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) { metafieldDefinitionCreate(definition: $definition) { createdDefinition { id name } userErrors { field message code } } }",
 "variables": {
    "definition": {
      "name": "Ingredients",
      "namespace": "bakery",
      "key": "ingredients",
      "description": "A list of ingredients used to make the product.",
      "type": "multi_line_text_field",
      "ownerType": "PRODUCT"
    }
  }
}'

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(
  `#graphql
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
      "definition": {
        "name": "Ingredients",
        "namespace": "bakery",
        "key": "ingredients",
        "description": "A list of ingredients used to make the product.",
        "type": "multi_line_text_field",
        "ownerType": "PRODUCT"
      }
    },
  },
);

const data = await response.json();

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
    metafieldDefinitionCreate(definition: $definition) {
      createdDefinition {
        id
        name
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "definition": {
    "name": "Ingredients",
    "namespace": "bakery",
    "key": "ingredients",
    "description": "A list of ingredients used to make the product.",
    "type": "multi_line_text_field",
    "ownerType": "PRODUCT"
  }
}

response = client.query(query: query, variables: variables)

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CreateMetafieldDefinition($definition: MetafieldDefinitionInput!) {
      metafieldDefinitionCreate(definition: $definition) {
        createdDefinition {
          id
          name
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
      "definition": {
        "name": "Ingredients",
        "namespace": "bakery",
        "key": "ingredients",
        "description": "A list of ingredients used to make the product.",
        "type": "multi_line_text_field",
        "ownerType": "PRODUCT"
      }
    },
  },
});

Input variables

JSON

1{
2  "definition": {
3    "name": "Ingredients",
4    "namespace": "bakery",
5    "key": "ingredients",
6    "description": "A list of ingredients used to make the product.",
7    "type": "multi_line_text_field",
8    "ownerType": "PRODUCT"
9  }
10}

Response

JSON

1{
2  "metafieldDefinitionCreate": {
3    "createdDefinition": {
4      "id": "gid://shopify/MetafieldDefinition/1071456166",
5      "name": "Ingredients"
6    },
7    "userErrors": []
8  }
9}