---
title: privateMetafieldUpsert - GraphQL Admin
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.
api_version: 2024-10
api_name: admin
type: mutation
api_type: graphql
source_url:
  html: >-
    https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/privateMetafieldUpsert
  md: >-
    https://shopify.dev/docs/api/admin-graphql/2024-10/mutations/privateMetafieldUpsert.txt
---

# private​Metafield​Upsert

mutation

Deprecated.

Metafields created using a reserved namespace are private by default. See our guide for [migrating private metafields](https://shopify.dev/docs/apps/custom-data/metafields/migrate-private-metafields). This will be removed in 2025-01.

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.

## Arguments

* input

  [Private​Metafield​Input!](https://shopify.dev/docs/api/admin-graphql/2024-10/input-objects/PrivateMetafieldInput)

  required

  Specifies the input fields for the private metafield.

***

## Private​Metafield​Upsert​Payload returns

* private​Metafield

  [Private​Metafield](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/PrivateMetafield)

  The private metafield that was created or updated.

* user​Errors

  [\[User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/2024-10/objects/UserError)

  non-null

  The list of errors that occurred from executing the mutation.

***

## Examples

* ### Create a private metafield for a resource

  #### Description

  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. If you are creating a private metafield for the \`Shop\` resource, then you don't need to specify an owner because \`Shop\` is the default owner.

  #### Query

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

  #### Variables

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

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) { privateMetafieldUpsert(input: $input) { privateMetafield { id namespace key value valueType } userErrors { field message } } }",
   "variables": {
      "input": {
        "owner": "gid://shopify/Product/632910392",
        "namespace": "wholesale",
        "key": "price",
        "valueInput": {
          "value": "5.00",
          "valueType": "STRING"
        }
      }
    }
  }'
  ```

  #### Remix

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

  const response = await admin.graphql(
    `#graphql
    mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {
      privateMetafieldUpsert(input: $input) {
        privateMetafield {
          id
          namespace
          key
          value
          valueType
        }
        userErrors {
          field
          message
        }
      }
    }`,
    {
      variables: {
          "input": {
              "owner": "gid://shopify/Product/632910392",
              "namespace": "wholesale",
              "key": "price",
              "valueInput": {
                  "value": "5.00",
                  "valueType": "STRING"
              }
          }
      },
    },
  );

  const data = await response.json();
  ```

  #### Ruby

  ```ruby
  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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {
      privateMetafieldUpsert(input: $input) {
        privateMetafield {
          id
          namespace
          key
          value
          valueType
        }
        userErrors {
          field
          message
        }
      }
    }
  QUERY

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

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

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {
        privateMetafieldUpsert(input: $input) {
          privateMetafield {
            id
            namespace
            key
            value
            valueType
          }
          userErrors {
            field
            message
          }
        }
      }`,
      "variables": {
          "input": {
              "owner": "gid://shopify/Product/632910392",
              "namespace": "wholesale",
              "key": "price",
              "valueInput": {
                  "value": "5.00",
                  "valueType": "STRING"
              }
          }
      },
    },
  });
  ```

  #### Response

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

* ### Update a private metafield

  #### Description

  You can update a private metafield's value and value type 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. In this example, the private metafield belongs to the \`Shop\` resource, so the owner field can be omitted.

  #### Query

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

  #### Variables

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

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) { privateMetafieldUpsert(input: $input) { privateMetafield { id namespace key value valueType } userErrors { field message } } }",
   "variables": {
      "input": {
        "namespace": "private_keys",
        "key": "fantastic_app",
        "valueInput": {
          "value": "TA710SP",
          "valueType": "STRING"
        }
      }
    }
  }'
  ```

  #### Remix

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

  const response = await admin.graphql(
    `#graphql
    mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {
      privateMetafieldUpsert(input: $input) {
        privateMetafield {
          id
          namespace
          key
          value
          valueType
        }
        userErrors {
          field
          message
        }
      }
    }`,
    {
      variables: {
          "input": {
              "namespace": "private_keys",
              "key": "fantastic_app",
              "valueInput": {
                  "value": "TA710SP",
                  "valueType": "STRING"
              }
          }
      },
    },
  );

  const data = await response.json();
  ```

  #### Ruby

  ```ruby
  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 privateMetafieldUpsert($input: PrivateMetafieldInput!) {
      privateMetafieldUpsert(input: $input) {
        privateMetafield {
          id
          namespace
          key
          value
          valueType
        }
        userErrors {
          field
          message
        }
      }
    }
  QUERY

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

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

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {
        privateMetafieldUpsert(input: $input) {
          privateMetafield {
            id
            namespace
            key
            value
            valueType
          }
          userErrors {
            field
            message
          }
        }
      }`,
      "variables": {
          "input": {
              "namespace": "private_keys",
              "key": "fantastic_app",
              "valueInput": {
                  "value": "TA710SP",
                  "valueType": "STRING"
              }
          }
      },
    },
  });
  ```

  #### Response

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

* ### privateMetafieldUpsert reference

[Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20privateMetafieldUpsert\(%24input%3A%20PrivateMetafieldInput!\)%20%7B%0A%20%20privateMetafieldUpsert\(input%3A%20%24input\)%20%7B%0A%20%20%20%20privateMetafield%20%7B%0A%20%20%20%20%20%20id%0A%20%20%20%20%20%20namespace%0A%20%20%20%20%20%20key%0A%20%20%20%20%20%20value%0A%20%20%20%20%20%20valueType%0A%20%20%20%20%7D%0A%20%20%20%20userErrors%20%7B%0A%20%20%20%20%20%20field%0A%20%20%20%20%20%20message%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22input%22%3A%20%7B%0A%20%20%20%20%22owner%22%3A%20%22gid%3A%2F%2Fshopify%2FProduct%2F632910392%22%2C%0A%20%20%20%20%22namespace%22%3A%20%22wholesale%22%2C%0A%20%20%20%20%22key%22%3A%20%22price%22%2C%0A%20%20%20%20%22valueInput%22%3A%20%7B%0A%20%20%20%20%20%20%22value%22%3A%20%225.00%22%2C%0A%20%20%20%20%20%20%22valueType%22%3A%20%22STRING%22%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D)

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


const response = await admin.graphql(
  `#graphql
  mutation privateMetafieldUpsert($input: PrivateMetafieldInput!) {
    privateMetafieldUpsert(input: $input) {
      privateMetafield {
        id
        namespace
        key
        value
        valueType
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "input": {
            "owner": "gid://shopify/Product/632910392",
            "namespace": "wholesale",
            "key": "price",
            "valueInput": {
                "value": "5.00",
                "valueType": "STRING"
            }
        }
    },
  },
);


const data = await response.json();
```

## Input variables

JSON

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

## Response

JSON

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