Choose a version:

metaobjectUpsert

mutation

Requires write_metaobjects access scope.

Creates or updates a Metaobject based on its handle. If a metaobject with the specified handle exists, the mutation updates it with the provided field values. If no matching metaobject exists, the mutation creates a new one.

The handle serves as a unique identifier within a metaobject type. Field values map to the MetaobjectDefinition's field keys and overwrite existing values during updates.

Anchor to Arguments

Arguments

Anchor to handlehandle

•MetaobjectHandleInput!

required

The identifier of the metaobject to upsert.

Show input fields

Anchor to metaobjectmetaobject

•MetaobjectUpsertInput!

required

The parameters to upsert the metaobject.

Show input fields

Was this section helpful?

Anchor to MetaobjectUpsertPayload returnsMetaobjectUpsertPayload returns

Anchor to metaobjectmetaobject •Metaobject: The created or updated metaobject.

Show fields
Anchor to userErrorsuserErrors •[MetaobjectUserError!]! non-null: The list of errors that occurred from executing the mutation.

Show fields

Was this section helpful?

Examples

Upsert a metaobject

Description

To upsert a metaobject, you can use the `metaobjectUpsert` mutation with the `handle` and `metaobject` input arguments which will either create a new metaobject or update an existing one. The following example uses upsert to create a new "color" metaobject with the handle "indigo-swatch" since it does not already exist.

Query

mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
  metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
    metaobject {
      handle
      hex: field(key: "hex") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Variables

{
  "handle": {
    "type": "color",
    "handle": "indigo-swatch"
  },
  "metaobject": {
    "fields": [
      {
        "key": "hex",
        "value": "#4B0082"
      }
    ]
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) { metaobjectUpsert(handle: $handle, metaobject: $metaobject) { metaobject { handle hex: field(key: \"hex\") { value } } userErrors { field message code } } }",
 "variables": {
    "handle": {
      "type": "color",
      "handle": "indigo-swatch"
    },
    "metaobject": {
      "fields": [
        {
          "key": "hex",
          "value": "#4B0082"
        }
      ]
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
    metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
      metaobject {
        handle
        hex: field(key: "hex") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "handle": {
            "type": "color",
            "handle": "indigo-swatch"
        },
        "metaobject": {
            "fields": [
                {
                    "key": "hex",
                    "value": "#4B0082"
                }
            ]
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

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 UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
    metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
      metaobject {
        handle
        hex: field(key: "hex") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "handle": {
    "type": "color",
    "handle": "indigo-swatch"
  },
  "metaobject": {
    "fields": [
      {
        "key": "hex",
        "value": "#4B0082"
      }
    ]
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
      metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
        metaobject {
          handle
          hex: field(key: "hex") {
            value
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "handle": {
            "type": "color",
            "handle": "indigo-swatch"
        },
        "metaobject": {
            "fields": [
                {
                    "key": "hex",
                    "value": "#4B0082"
                }
            ]
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
  metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
    metaobject {
      handle
      hex: field(key: "hex") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "handle": {
    "type": "color",
    "handle": "indigo-swatch"
  },
  "metaobject": {
    "fields": [
      {
        "key": "hex",
        "value": "#4B0082"
      }
    ]
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
        metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
          metaobject {
            handle
            hex: field(key: "hex") {
              value
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "handle": {
            "type": "color",
            "handle": "indigo-swatch"
        },
        "metaobject": {
            "fields": [
                {
                    "key": "hex",
                    "value": "#4B0082"
                }
            ]
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "metaobjectUpsert": {
    "metaobject": {
      "handle": "indigo-swatch",
      "hex": {
        "value": "#4B0082"
      }
    },
    "userErrors": []
  }
}

metaobjectUpsert reference

Examples

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

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

const response = await admin.graphql(

`#graphql

mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {

metaobjectUpsert(handle: $handle, metaobject: $metaobject) {

metaobject {

handle

hex: field(key: "hex") {

value

}

userErrors {

field

message

code

}

}`,

{

variables: {

"handle": {

"type": "color",

"handle": "indigo-swatch"

"metaobject": {

"fields": [

{

"key": "hex",

"value": "#4B0082"

}

]

}

);

const json = await response.json();

return json.data;

}

GQL

mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
  metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
    metaobject {
      handle
      hex: field(key: "hex") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) { metaobjectUpsert(handle: $handle, metaobject: $metaobject) { metaobject { handle hex: field(key: \"hex\") { value } } userErrors { field message code } } }",
 "variables": {
    "handle": {
      "type": "color",
      "handle": "indigo-swatch"
    },
    "metaobject": {
      "fields": [
        {
          "key": "hex",
          "value": "#4B0082"
        }
      ]
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
    metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
      metaobject {
        handle
        hex: field(key: "hex") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }`,
  {
    variables: {
        "handle": {
            "type": "color",
            "handle": "indigo-swatch"
        },
        "metaobject": {
            "fields": [
                {
                    "key": "hex",
                    "value": "#4B0082"
                }
            ]
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
      metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
        metaobject {
          handle
          hex: field(key: "hex") {
            value
          }
        }
        userErrors {
          field
          message
          code
        }
      }
    }`,
    "variables": {
        "handle": {
            "type": "color",
            "handle": "indigo-swatch"
        },
        "metaobject": {
            "fields": [
                {
                    "key": "hex",
                    "value": "#4B0082"
                }
            ]
        }
    },
  },
});

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 UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
    metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
      metaobject {
        handle
        hex: field(key: "hex") {
          value
        }
      }
      userErrors {
        field
        message
        code
      }
    }
  }
QUERY

variables = {
  "handle": {
    "type": "color",
    "handle": "indigo-swatch"
  },
  "metaobject": {
    "fields": [
      {
        "key": "hex",
        "value": "#4B0082"
      }
    ]
  }
}

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

Shopify CLI

shopify app execute \
--query \
'mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
  metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
    metaobject {
      handle
      hex: field(key: "hex") {
        value
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}' \
--variables \
'{
  "handle": {
    "type": "color",
    "handle": "indigo-swatch"
  },
  "metaobject": {
    "fields": [
      {
        "key": "hex",
        "value": "#4B0082"
      }
    ]
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {
        metaobjectUpsert(handle: $handle, metaobject: $metaobject) {
          metaobject {
            handle
            hex: field(key: "hex") {
              value
            }
          }
          userErrors {
            field
            message
            code
          }
        }
      }
    `,
    variables: {
        "handle": {
            "type": "color",
            "handle": "indigo-swatch"
        },
        "metaobject": {
            "fields": [
                {
                    "key": "hex",
                    "value": "#4B0082"
                }
            ]
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"handle": {

"type": "color",

"handle": "indigo-swatch"

"metaobject": {

"fields": [

{

"key": "hex",

"value": "#4B0082"

}

]

}

Response

JSON

{

"metaobjectUpsert": {

"metaobject": {

"handle": "indigo-swatch",

"hex": {

"value": "#4B0082"

}

"userErrors": []

}