We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

Working with metafields using the GraphQL Admin API

Using GraphQL Admin API, you can add metafields and private metafields to Shopify resources, such as a product, customer, or blog post. Metafields and private metafields are distinct types, so there are differences in how you create, update, and delete them.

This guide focuses on GraphQL. You can also use metafields with the REST Admin API. To learn more, see the the Metafield reference.

Creating metafields

An app can create any number of metafields for a resource, and they will be accessible to any app.

To create metafields, use a GraphQL mutation to create or update the resource that you want the metafield to belong to. The following example adds a metafield to a product by using the productUpdate mutation.

POST /admin/api/unstable/graphql.json

mutation($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      metafields(first: 100) {
        edges {
          node {
            id
            namespace
            key
            value
          }
        }
      }
    }
  }
}

Variables

{
  "input" : {
    "id": "gid://shopify/Product/1",
    "metafields": [
      {
        "namespace": "instructions",
        "key": "wash",
        "valueInput": {
          "value": "cold wash",
          "valueType": "STRING"
        }
      }
    ]
  }
}

JSON response

{
  "data": {
    "productUpdate": {
      "product": {
        "metafields": {
          "edges": [
            {
              "node": {
                "namespace": "instructions",
                "key": "wash",
                "value": "cold wash"
              }
            }
          ]
        }
      }
    }
  }
}

Retrieving metafields

When you query a resource, you can retrieve its metafields individually or in a list.

Retrieve a single metafield

Use the metafield field to return a single metafield. Specify the metafield that you want to retrieve by using the namespace and key arguments.

POST /admin/api/unstable/graphql.json

query {
  product(id: "gid://shopify/Product/1") {
    metafield(namespace: "instructions", key: "wash") {
      value
    }
  }
}

JSON response

{
  "data": {
    "product": {
      "metafield": {
        "value": "cold wash"
      }
    }
  }
}

Retrieve a list of metafields

Use the metafields connection to retrieve a list of metafields. You can include the namespace argument to filter the returned results.

POST /admin/api/unstable/graphql.json

query {
  product(id: "gid://shopify/Product/1") {
    metafields(namespace: "instructions", first: 100) {
      edges {
        node {
          id
          namespace
          key
          value
        }
      }
    }
  }
}

JSON response

{
  "data": {
    "product": {
      "metafields": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/Metafield/4137445720120",
              "namespace": "instructions",
              "key": "wash",
              "value": "cold wash"
            }
          },
          {
            "node": {
              "id": "gid://shopify/Metafield/4143381872696",
              "namespace": "instructions",
              "key": "dry",
              "value": "tumble dry"
            }
          }
        ]
      }
    }
  }
}

Updating metafields

To update a metafield, use a GraphQL mutation to update the owning resource, and include the metafield in the mutation input. Specify the owning resource and the metafields that you're updating by their IDs. The following example updates a metafield that belongs to a product by using the productUpdate mutation.

POST /admin/api/unstable/graphql.json

mutation ($input: ProductInput!){
  productUpdate(input: $input) {
    product {
      metafields(first:10) {
        edges {
          node {
            key
            value
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "id": "gid://shopify/Product/1",
    "metafields": [
      {
        "id": "gid://shopify/Metafield/4143381872696",
        "value": "hang dry"
      }
    ]
  }
}

JSON response

{
  "data": {
    "productUpdate": {
      "product": {
        "metafields": {
          "edges": [
            {
              "node": {
                "key": "wash",
                "value": "cold wash"
              }
            },
            {
              "node": {
                "key": "dry",
                "value": "hang dry"
              }
            }
          ]
        }
      }
    }
  }
}

Deleting metafields

Use the metafieldDelete mutation to delete a metafield. Specify the metafield that you want to delete by including its ID in the mutation input.

POST /admin/api/unstable/graphql.json

mutation($input: MetafieldDeleteInput!) {
  metafieldDelete(input: $input) {
    deletedId
  }
  userErrors {
    field
    message
  }
}

Variables

{
  "input": {
    "id": "gid://shopify/Metafield/1"
  }
}

JSON response

{
  "metafieldDelete" : {
    "deletedId": "gid://shopify/Metafield/1",
    "usserErrors": []
  }
}

Creating private metafields

Each app can create a maximum of 10 private metafields per shop resource. There are two ways to create a private metafield:

Creating private metafields using privateMetafieldUpsert

Use the privateMetafieldUpsert mutation to create a private metafield for an existing resource. Specify the owning resource by providing its ID as part of the input.

POST /admin/api/unstable/graphql.json

mutation($input: PrivateMetafieldInput!) {
  privateMetafieldUpsert(input: $input) {
    privateMetafield {
      namespace
      key
      value
      valueType
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "input": {
    "owner": "gid://shopify/Product/10079787532",
    "namespace": "wholesale",
    "key": "wholesale_price",
    "valueInput": {
      "value": "5.00",
      "valueType": "STRING"
    }
  }
}

JSON response

{
  "data": {
    "privateMetafieldUpsert": {
      "privateMetafield": {
        "namespace": "wholesale",
        "key": "wholesale_price",
        "value": "5.00",
        "valueType": "STRING"
      },
      "userErrors": []
    }
  }
}

Creating or updating the owning resource

You can create a private metafield by including it as part of the input when you create or update the private metafield's owning resource.

The following mutations accept an array of private metafields as part of their input object:

  • collectionCreate
  • collectionUpdate
  • customerCreate
  • customerUpdate
  • draftOrderCreate
  • draftOrderUpdate
  • orderUpdate
  • productCreate
  • productUpdate
  • productVariantCreate
  • productVariantUpdate

The example below uses the productUpdate mutation to create a private metafield for an existing product.

POST /admin/api/unstable/graphql.json

mutation($input: ProductInput!) {
  productUpdate(input: $input){
    product {
      privateMetafields(first:10) {
        edges {
          node {
            namespace
            key
            value
          }
        }
      }
    }
  }
}

Variables

{
  "input":{
    "id":"gid://shopify/Product/10079785100",
    "privateMetafields": [
      {
        "owner": "gid://shopify/Product/10079785100",
        "namespace": "wholesale",
        "key": "wholesale_price",
        "valueInput": {
          "value":"25",
          "valueType": "INTEGER"
        }
      }
    ]
  }
}

JSON response

{
  "data": {
    "productUpdate": {
      "product": {
        "privateMetafields": {
          "edges": [
            {
              "node": {
                "namespace": "wholesale",
                "key": "wholesale_price",
                "value": "25"
              }
            }
          ]
        }
      }
    }
  }
}

Retrieving private metafields

When you query a resource, you can retrieve its private metafields individually or in a list.

Retrieve a single private metafield

Use the privateMetafield field to return a single private metafield. Specify the private metafield that you want to retrieve by using the namespace and key arguments.

POST /admin/api/unstable/graphql.json

query {
  product(id: "gid://shopify/Product/1") {
    privateMetafield(namespace: "wholesale", key: "wholesale_price") {
      value
    }
  }
}

JSON response

{
  "data": {
    "product": {
      "privateMetafield": {
        "value": "15.00"
      }
    }
  }
}

Retrieve a list of private metafields

Use the privateMetafields connection to retrieve a list of metafields. You can include the namespace argument to filter the returned results.

POST /admin/api/unstable/graphql.json

query {
  product(id: "gid://shopify/Product/1") {
    privateMetafields(namespace: "wholesale", first: 10) {
      edges {
        node {
          id
          namespace
          key
          value
        }
      }
    }
  }
}

JSON response

{
  "data": {
    "product": {
      "privateMetafields": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/PrivateMetafield/131128",
              "namespace": "wholesale",
              "key": "wholesale_price",
              "value": "15.00"
            }
          }
        ]
      }
    }
  }
}

Updating private metafields

There are two ways to update private metafields:

Updating private metafields using privateMetafieldUpsert

You can update a private metafield by using the privateMetafieldUpsert mutation. As part of the input, specify the owning resource by its ID, and specify the private metafield by its namespace and key.

POST /admin/api/unstable/graphql.json

mutation($input: PrivateMetafieldInput!) {
  privateMetafieldUpsert(input: $input) {
    privateMetafield {
      namespace
      key
      value
    }
  }
}

Variables

{
  "input": {
    "owner":"gid://shopify/Product/10079785100",
    "namespace": "wholesale",
    "key": "wholesale_price",
    "valueInput": {
      "value": "25",
      "valueType": "INTEGER"
    }
  }
}

JSON response

{
  "input": {
    "owner":"gid://shopify/Product/10079785100",
    "namespace": "wholesale",
    "key": "wholesale_price",
    "valueInput": {
      "value": "50",
      "valueType": "INTEGER"
    }
  }
}

Updating the owning resource

You can update a private metafield by using a GraphQL mutation to update the owning resource and including the private metafield as part of the mutation input. Specify the owning resource by its ID, and specify the private metafield by its namespace and key. The following GraphQL mutations accept private metafields as part of their input:

  • collectionUpdate
  • customerUpdate
  • draftOrderUpdate
  • orderUpdate
  • productUpdate
  • productVariantUpdate

The following mutation uses the productUpdate mutation to update a private metafield that belongs to a product.

POST /admin/api/unstable/graphql.json

mutation ($input: ProductInput!){
  productUpdate(input: $input) {
    product {
      privateMetafields(first:10) {
        edges {
          node {
            key
            value
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "id": "gid://shopify/Product/10079785100",
    "privateMetafields": [
      {
        "namespace": "wholesale",
        "key":"wholesale_price",
        "valueInput": {
          "value": "50",
          "valueType": "INTEGER"
        }
      }
    ]
  }
}

JSON response

{
  "data": {
    "productUpdate": {
      "product": {
        "privateMetafields": {
          "edges": [
            {
              "node": {
                "key": "wholesale_price",
                "value": "50"
              }
            }
          ]
        }
      }
    }
  }
}

Deleting private metafields

Use the privateMetafieldDelete mutation to delete a private metafield. Specify the private metafield that you want to delete by providing the following data in the input:

  • its namespace
  • its key
  • the ID of its owning resource

POST /admin/api/unstable/graphql.json

mutation($input: PrivateMetafieldDeleteInput!) {
  privateMetafieldDelete(input: $input) {
    deletedPrivateMetafieldId
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "input": {
    "owner": "gid://shopify/Product/1",
    "namespace": "wholesale",
    "key": "wholesale_price"
  }
}

JSON response

{
  "data": {
    "privateMetafieldDelete": {
      "deletedPrivateMetafieldId": "gid://shopify/PrivateMetafield/98360",
      "userErrors": []
    }
  }
}

Sign up for a Partner account to get started.

Sign up