privateMetafieldUpsert - admin-graphql - MUTATION

Version: 2024-04

Description:

Creates or updates a private metafield. Use private metafields when you don't want the metafield data to be accessible by merchants or other apps. Private metafields are accessible only by the application that created them and only from the GraphQL Admin API. An application can create a maximum of 10 private metafields per shop resource.

Access Scopes

Arguments

• input: PrivateMetafieldInput! - Specifies the input fields for the private metafield.

Returns

• privateMetafield: PrivateMetafield The private metafield that was created or updated.
• userErrors: UserError! The list of errors that occurred from executing the mutation.

Examples

• Create a private metafield for a resource

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) { privateMetafieldUpsert(input: $input) { privateMetafield { id namespace key value valueType } userErrors { field message } } }\",\n \"variables\": {\n    \"input\": {\n      \"owner\": \"gid://shopify/Product/632910392\",\n      \"namespace\": \"wholesale\",\n      \"key\": \"price\",\n      \"valueInput\": {\n        \"value\": \"5.00\",\n        \"valueType\": \"STRING\"\n      }\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n      privateMetafieldUpsert(input: $input) {\n        privateMetafield {\n          id\n          namespace\n          key\n          value\n          valueType\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }`,\n    \"variables\": {\n      \"input\": {\n        \"owner\": \"gid://shopify/Product/632910392\",\n        \"namespace\": \"wholesale\",\n        \"key\": \"price\",\n        \"valueInput\": {\n          \"value\": \"5.00\",\n          \"valueType\": \"STRING\"\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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n    privateMetafieldUpsert(input: $input) {\n      privateMetafield {\n        id\n        namespace\n        key\n        value\n        valueType\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"input\": {\n    \"owner\": \"gid://shopify/Product/632910392\",\n    \"namespace\": \"wholesale\",\n    \"key\": \"price\",\n    \"valueInput\": {\n      \"value\": \"5.00\",\n      \"valueType\": \"STRING\"\n    }\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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n    privateMetafieldUpsert(input: $input) {\n      privateMetafield {\n        id\n        namespace\n        key\n        value\n        valueType\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"input\" => [\n    \"owner\" => \"gid://shopify/Product/632910392\",\n    \"namespace\" => \"wholesale\",\n    \"key\" => \"price\",\n    \"valueInput\" => [\n      \"value\" => \"5.00\",\n      \"valueType\" => \"STRING\",\n    ],\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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n    privateMetafieldUpsert(input: $input) {\n      privateMetafield {\n        id\n        namespace\n        key\n        value\n        valueType\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"input\": {\n        \"owner\": \"gid://shopify/Product/632910392\",\n        \"namespace\": \"wholesale\",\n        \"key\": \"price\",\n        \"valueInput\": {\n          \"value\": \"5.00\",\n          \"valueType\": \"STRING\"\n        }\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n  privateMetafieldUpsert(input: $input) {\n    privateMetafield {\n      id\n      namespace\n      key\n      value\n      valueType\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}"
        

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

  response: {
    "data": {
      "privateMetafieldUpsert": {
        "privateMetafield": {
          "id": "gid://shopify/PrivateMetafield/1060470848",
          "namespace": "wholesale",
          "key": "price",
          "value": "5.00",
          "valueType": "STRING"
        },
        "userErrors": []
      }
    }
  }

  Create a private metafield from the resources' mutations

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation productUpdate($input: ProductInput!) { productUpdate(input: $input) { product { privateMetafields(first: 10) { edges { node { namespace key value } } } } } }\",\n \"variables\": {\n    \"input\": {\n      \"id\": \"gid://shopify/Product/632910392\",\n      \"privateMetafields\": [\n        {\n          \"owner\": \"gid://shopify/Product/632910392\",\n          \"namespace\": \"wholesale\",\n          \"key\": \"price\",\n          \"valueInput\": {\n            \"value\": \"5\",\n            \"valueType\": \"INTEGER\"\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 productUpdate($input: ProductInput!) {\n      productUpdate(input: $input) {\n        product {\n          privateMetafields(first: 10) {\n            edges {\n              node {\n                namespace\n                key\n                value\n              }\n            }\n          }\n        }\n      }\n    }`,\n    \"variables\": {\n      \"input\": {\n        \"id\": \"gid://shopify/Product/632910392\",\n        \"privateMetafields\": [\n          {\n            \"owner\": \"gid://shopify/Product/632910392\",\n            \"namespace\": \"wholesale\",\n            \"key\": \"price\",\n            \"valueInput\": {\n              \"value\": \"5\",\n              \"valueType\": \"INTEGER\"\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 productUpdate($input: ProductInput!) {\n    productUpdate(input: $input) {\n      product {\n        privateMetafields(first: 10) {\n          edges {\n            node {\n              namespace\n              key\n              value\n            }\n          }\n        }\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"input\": {\n    \"id\": \"gid://shopify/Product/632910392\",\n    \"privateMetafields\": [{\"owner\"=>\"gid://shopify/Product/632910392\", \"namespace\"=>\"wholesale\", \"key\"=>\"price\", \"valueInput\"=>{\"value\"=>\"5\", \"valueType\"=>\"INTEGER\"}}]\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 productUpdate($input: ProductInput!) {\n    productUpdate(input: $input) {\n      product {\n        privateMetafields(first: 10) {\n          edges {\n            node {\n              namespace\n              key\n              value\n            }\n          }\n        }\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"input\" => [\n    \"id\" => \"gid://shopify/Product/632910392\",\n    \"privateMetafields\" => [{\"owner\"=>\"gid://shopify/Product/632910392\", \"namespace\"=>\"wholesale\", \"key\"=>\"price\", \"valueInput\"=>{\"value\"=>\"5\", \"valueType\"=>\"INTEGER\"}}],\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 productUpdate($input: ProductInput!) {\n    productUpdate(input: $input) {\n      product {\n        privateMetafields(first: 10) {\n          edges {\n            node {\n              namespace\n              key\n              value\n            }\n          }\n        }\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"input\": {\n        \"id\": \"gid://shopify/Product/632910392\",\n        \"privateMetafields\": [\n          {\n            \"owner\": \"gid://shopify/Product/632910392\",\n            \"namespace\": \"wholesale\",\n            \"key\": \"price\",\n            \"valueInput\": {\n              \"value\": \"5\",\n              \"valueType\": \"INTEGER\"\n            }\n          }\n        ]\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation productUpdate($input: ProductInput!) {\n  productUpdate(input: $input) {\n    product {\n      privateMetafields(first: 10) {\n        edges {\n          node {\n            namespace\n            key\n            value\n          }\n        }\n      }\n    }\n  }\n}"
        

  input: {
    "input": {
      "id": "gid://shopify/Product/632910392",
      "privateMetafields": [
        {
          "owner": "gid://shopify/Product/632910392",
          "namespace": "wholesale",
          "key": "price",
          "valueInput": {
            "value": "5",
            "valueType": "INTEGER"
          }
        }
      ]
    }
  }

  response: {
    "data": {
      "productUpdate": {
        "product": {
          "privateMetafields": {
            "edges": [
              {
                "node": {
                  "namespace": "wholesale",
                  "key": "price",
                  "value": "5"
                }
              }
            ]
          }
        }
      }
    }
  }

  Update a private metafield

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) { privateMetafieldUpsert(input: $input) { privateMetafield { id namespace key value valueType } userErrors { field message } } }\",\n \"variables\": {\n    \"input\": {\n      \"namespace\": \"private_keys\",\n      \"key\": \"fantastic_app\",\n      \"valueInput\": {\n        \"value\": \"TA710SP\",\n        \"valueType\": \"STRING\"\n      }\n    }\n  }\n}'\n"
          Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n  data: {\n    \"query\": `mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n      privateMetafieldUpsert(input: $input) {\n        privateMetafield {\n          id\n          namespace\n          key\n          value\n          valueType\n        }\n        userErrors {\n          field\n          message\n        }\n      }\n    }`,\n    \"variables\": {\n      \"input\": {\n        \"namespace\": \"private_keys\",\n        \"key\": \"fantastic_app\",\n        \"valueInput\": {\n          \"value\": \"TA710SP\",\n          \"valueType\": \"STRING\"\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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n    privateMetafieldUpsert(input: $input) {\n      privateMetafield {\n        id\n        namespace\n        key\n        value\n        valueType\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"input\": {\n    \"namespace\": \"private_keys\",\n    \"key\": \"fantastic_app\",\n    \"valueInput\": {\n      \"value\": \"TA710SP\",\n      \"valueType\": \"STRING\"\n    }\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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n    privateMetafieldUpsert(input: $input) {\n      privateMetafield {\n        id\n        namespace\n        key\n        value\n        valueType\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"input\" => [\n    \"namespace\" => \"private_keys\",\n    \"key\" => \"fantastic_app\",\n    \"valueInput\" => [\n      \"value\" => \"TA710SP\",\n      \"valueType\" => \"STRING\",\n    ],\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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n    privateMetafieldUpsert(input: $input) {\n      privateMetafield {\n        id\n        namespace\n        key\n        value\n        valueType\n      }\n      userErrors {\n        field\n        message\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"input\": {\n        \"namespace\": \"private_keys\",\n        \"key\": \"fantastic_app\",\n        \"valueInput\": {\n          \"value\": \"TA710SP\",\n          \"valueType\": \"STRING\"\n        }\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {\n  privateMetafieldUpsert(input: $input) {\n    privateMetafield {\n      id\n      namespace\n      key\n      value\n      valueType\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}"
        

  input: {
    "input": {
      "namespace": "private_keys",
      "key": "fantastic_app",
      "valueInput": {
        "value": "TA710SP",
        "valueType": "STRING"
      }
    }
  }

  response: {
    "data": {
      "privateMetafieldUpsert": {
        "privateMetafield": {
          "id": "gid://shopify/PrivateMetafield/1060470847",
          "namespace": "private_keys",
          "key": "fantastic_app",
          "value": "TA710SP",
          "valueType": "STRING"
        },
        "userErrors": []
      }
    }
  }

  Update a private metafield using the update mutation for the owning resource

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation productUpdate($input: ProductInput!) { productUpdate(input: $input) { product { privateMetafields(first: 10) { edges { node { namespace key value valueType } } } } } }\",\n \"variables\": {\n    \"input\": {\n      \"id\": \"gid://shopify/Product/632910392\",\n      \"privateMetafields\": [\n        {\n          \"namespace\": \"wholesale\",\n          \"key\": \"price\",\n          \"valueInput\": {\n            \"value\": \"50\",\n            \"valueType\": \"INTEGER\"\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 productUpdate($input: ProductInput!) {\n      productUpdate(input: $input) {\n        product {\n          privateMetafields(first: 10) {\n            edges {\n              node {\n                namespace\n                key\n                value\n                valueType\n              }\n            }\n          }\n        }\n      }\n    }`,\n    \"variables\": {\n      \"input\": {\n        \"id\": \"gid://shopify/Product/632910392\",\n        \"privateMetafields\": [\n          {\n            \"namespace\": \"wholesale\",\n            \"key\": \"price\",\n            \"valueInput\": {\n              \"value\": \"50\",\n              \"valueType\": \"INTEGER\"\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 productUpdate($input: ProductInput!) {\n    productUpdate(input: $input) {\n      product {\n        privateMetafields(first: 10) {\n          edges {\n            node {\n              namespace\n              key\n              value\n              valueType\n            }\n          }\n        }\n      }\n    }\n  }\nQUERY\n\nvariables = {\n  \"input\": {\n    \"id\": \"gid://shopify/Product/632910392\",\n    \"privateMetafields\": [{\"namespace\"=>\"wholesale\", \"key\"=>\"price\", \"valueInput\"=>{\"value\"=>\"50\", \"valueType\"=>\"INTEGER\"}}]\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 productUpdate($input: ProductInput!) {\n    productUpdate(input: $input) {\n      product {\n        privateMetafields(first: 10) {\n          edges {\n            node {\n              namespace\n              key\n              value\n              valueType\n            }\n          }\n        }\n      }\n    }\n  }\nQUERY;\n\n$variables = [\n  \"input\" => [\n    \"id\" => \"gid://shopify/Product/632910392\",\n    \"privateMetafields\" => [{\"namespace\"=>\"wholesale\", \"key\"=>\"price\", \"valueInput\"=>{\"value\"=>\"50\", \"valueType\"=>\"INTEGER\"}}],\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 productUpdate($input: ProductInput!) {\n    productUpdate(input: $input) {\n      product {\n        privateMetafields(first: 10) {\n          edges {\n            node {\n              namespace\n              key\n              value\n              valueType\n            }\n          }\n        }\n      }\n    }\n  }`,\n  {\n    variables: {\n      \"input\": {\n        \"id\": \"gid://shopify/Product/632910392\",\n        \"privateMetafields\": [\n          {\n            \"namespace\": \"wholesale\",\n            \"key\": \"price\",\n            \"valueInput\": {\n              \"value\": \"50\",\n              \"valueType\": \"INTEGER\"\n            }\n          }\n        ]\n      }\n    },\n  },\n);\n\nconst data = await response.json();\n"
          Graphql query: "mutation productUpdate($input: ProductInput!) {\n  productUpdate(input: $input) {\n    product {\n      privateMetafields(first: 10) {\n        edges {\n          node {\n            namespace\n            key\n            value\n            valueType\n          }\n        }\n      }\n    }\n  }\n}"
        

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

  response: {
    "data": {
      "productUpdate": {
        "product": {
          "privateMetafields": {
            "edges": [
              {
                "node": {
                  "namespace": "wholesale",
                  "key": "price",
                  "value": "50",
                  "valueType": "INTEGER"
                }
              }
            ]
          }
        }
      }
    }
  }