metaobject Upsertmutation
mutation
2024-10latest
Requires write
access scope.
Retrieves a metaobject by handle, then updates it with the provided input values. If no matching metaobject is found, a new metaobject is created with the provided input values.
Arguments
The identifier of the metaobject to upsert.
The parameters to upsert the metaobject.
Was this section helpful?
MetaobjectUpsertPayload returns
The created or updated metaobject.
The list of errors that occurred from executing the mutation.
Was this section helpful?
Code examples for MUTATION: metaobjectUpsert
Query Reference for MUTATION: metaobjectUpsert
"mutation metaobjectUpsert($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {\n metaobjectUpsert(handle: $handle, metaobject: $metaobject) {\n metaobject {\n # Metaobject fields\n }\n userErrors {\n field\n message\n }\n }\n}"
Input Reference for MUTATION: metaobjectUpsert
"{\n \"handle\": {\n \"handle\": \"<your-handle>\",\n \"type\": \"<your-type>\"\n },\n \"metaobject\": {\n \"capabilities\": {\n \"onlineStore\": {\n \"templateSuffix\": \"<your-templateSuffix>\"\n },\n \"publishable\": {\n \"status\": \"ACTIVE\"\n }\n },\n \"fields\": [\n {\n \"key\": \"<your-key>\",\n \"value\": \"<your-value>\"\n }\n ],\n \"handle\": \"<your-handle>\"\n }\n}"
Schema Reference for MUTATION: metaobjectUpsert
"input MetaobjectHandleInput {\n handle: String!\n type: String!\n}\n\ninput MetaobjectUpsertInput {\n capabilities: MetaobjectCapabilityDataInput\n fields: [MetaobjectFieldInput!]\n handle: String\n}\n\ninput MetaobjectCapabilityDataInput {\n onlineStore: MetaobjectCapabilityDataOnlineStoreInput\n publishable: MetaobjectCapabilityDataPublishableInput\n}\n\ninput MetaobjectFieldInput {\n key: String!\n value: String!\n}\n"
Display Examples for MUTATION: metaobjectUpsert
[ { "example": { "type_name": "metaobjectupsert", "title": "Upsert a metaobject", "description": "To upsert a metaobject, you can use the `metaobjectUpsert` mutation with the `handle` and `metaobject`\ninput arguments which will either create a new metaobject or update an existing one.\nThe following example uses upsert to create a new \"color\" metaobject with the handle \"indigo-swatch\"\nsince it does not already exist.\n", "query_string": "mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {\n metaobjectUpsert(handle: $handle, metaobject: $metaobject) {\n metaobject {\n handle\n hex: field(key: \"hex\") {\n value\n }\n }\n userErrors {\n field\n message\n code\n }\n }\n}", "variables": { "handle": { "type": "color", "handle": "indigo-swatch" }, "metaobject": { "fields": [ { "key": "hex", "value": "#4B0082" } ] } }, "response": { "data": { "metaobjectUpsert": { "metaobject": { "handle": "indigo-swatch", "hex": { "value": "#4B0082" } }, "userErrors": [] } } }, "api_name": "admin", "minimum_api_version": "2023-10", "maximum_api_version": "unstable", "location": "/components/content/metaobjects/test/unit/graph_api/admin/mutations/metaobject_upsert_test.rb", "curl_example": "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-10/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) { metaobjectUpsert(handle: $handle, metaobject: $metaobject) { metaobject { handle hex: field(key: \\\"hex\\\") { value } } userErrors { field message code } } }\",\n \"variables\": {\n \"handle\": {\n \"type\": \"color\",\n \"handle\": \"indigo-swatch\"\n },\n \"metaobject\": {\n \"fields\": [\n {\n \"key\": \"hex\",\n \"value\": \"#4B0082\"\n }\n ]\n }\n }\n}'\n", "remix_example": "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {\n metaobjectUpsert(handle: $handle, metaobject: $metaobject) {\n metaobject {\n handle\n hex: field(key: \"hex\") {\n value\n }\n }\n userErrors {\n field\n message\n code\n }\n }\n }`,\n {\n variables: {\n \"handle\": {\n \"type\": \"color\",\n \"handle\": \"indigo-swatch\"\n },\n \"metaobject\": {\n \"fields\": [\n {\n \"key\": \"hex\",\n \"value\": \"#4B0082\"\n }\n ]\n }\n },\n },\n);\n\nconst data = await response.json();\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 UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {\n metaobjectUpsert(handle: $handle, metaobject: $metaobject) {\n metaobject {\n handle\n hex: field(key: \"hex\") {\n value\n }\n }\n userErrors {\n field\n message\n code\n }\n }\n }\nQUERY\n\nvariables = {\n \"handle\": {\n \"type\": \"color\",\n \"handle\": \"indigo-swatch\"\n },\n \"metaobject\": {\n \"fields\": [{\"key\"=>\"hex\", \"value\"=>\"#4B0082\"}]\n }\n}\n\nresponse = client.query(query: query, variables: variables)\n", "node_example": "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {\n metaobjectUpsert(handle: $handle, metaobject: $metaobject) {\n metaobject {\n handle\n hex: field(key: \"hex\") {\n value\n }\n }\n userErrors {\n field\n message\n code\n }\n }\n }`,\n \"variables\": {\n \"handle\": {\n \"type\": \"color\",\n \"handle\": \"indigo-swatch\"\n },\n \"metaobject\": {\n \"fields\": [\n {\n \"key\": \"hex\",\n \"value\": \"#4B0082\"\n }\n ]\n }\n },\n },\n});\n", "php_example": "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = <<<QUERY\n mutation UpsertMetaobject($handle: MetaobjectHandleInput!, $metaobject: MetaobjectUpsertInput!) {\n metaobjectUpsert(handle: $handle, metaobject: $metaobject) {\n metaobject {\n handle\n hex: field(key: \"hex\") {\n value\n }\n }\n userErrors {\n field\n message\n code\n }\n }\n }\nQUERY;\n\n$variables = [\n \"handle\" => [\n \"type\" => \"color\",\n \"handle\" => \"indigo-swatch\",\n ],\n \"metaobject\" => [\n \"fields\" => [{\"key\"=>\"hex\", \"value\"=>\"#4B0082\"}],\n ],\n];\n\n$response = $client->query([\"query\" => $query, \"variables\" => $variables]);\n" }, "titleStringKey": "variables", "inputVariableEntries": [ { "arg": { "name": "handle", "description": "The identifier of the metaobject to upsert.", "type": { "kind": "INPUT_OBJECT", "name": "MetaobjectHandleInput", "list": false, "non_null": true }, "defaultValue": null, "typeSignature": "MetaobjectHandleInput!", "isDeprecated": false, "deprecationReason": null, "kind": "ARGUMENT" }, "key": "handle", "argValue": " {\"type\":\"color\",\"handle\":\"indigo-swatch\"}", "typeKind": "MUTATION" }, { "arg": { "name": "metaobject", "description": "The parameters to upsert the metaobject.", "type": { "kind": "INPUT_OBJECT", "name": "MetaobjectUpsertInput", "list": false, "non_null": true }, "defaultValue": null, "typeSignature": "MetaobjectUpsertInput!", "isDeprecated": false, "deprecationReason": null, "kind": "ARGUMENT" }, "key": "metaobject", "argValue": " {\"fields\":[{\"key\":\"hex\",\"value\":\"#4B0082\"}]}", "typeKind": "MUTATION" } ] } ]