# combinedListingUpdate - admin-graphql - MUTATION Version: 2024-10 ## Description Add, remove and update `CombinedListing`s of a given Product. `CombinedListing`s are comprised of multiple products to create a single listing. There are two kinds of products used in a `CombinedListing`: 1. Parent products 2. Child products The parent product is created with a `productCreate` with a `CombinedListingRole` of `PARENT`. Once created, you can associate child products with the parent product using this mutation. Parent products represent the idea of a product (e.g. Shoe). Child products represent a particular option value (or combination of option values) of a parent product. For instance, with your Shoe parent product, you may have several child products representing specific colors of the shoe (e.g. Shoe - Blue). You could also have child products representing more than a single option (e.g. Shoe - Blue/Canvas, Shoe - Blue/Leather, etc...). The combined listing is the association of parent product to one or more child products. Learn more about [Combined Listings](https://shopify.dev/apps/selling-strategies/combined-listings). ### Access Scopes `write_products` access scope. Also: The user must have permission to manage products. ## Arguments * [optionsAndValues](/docs/api/admin-graphql/2024-10/input-objects/OptionAndValueInput): OptionAndValueInput - The ordered options and values to be used by the combined listing. Options and values will be reordered to match the order specified here. * [parentProductId](/docs/api/admin-graphql/2024-10/scalars/ID): ID! - The ID of the parent product. * [productsAdded](/docs/api/admin-graphql/2024-10/input-objects/ChildProductRelationInput): ChildProductRelationInput - The child products to add and their assigned options and option values. * [productsEdited](/docs/api/admin-graphql/2024-10/input-objects/ChildProductRelationInput): ChildProductRelationInput - The child products to edit and their assigned options and option values. * [productsRemovedIds](/docs/api/admin-graphql/2024-10/scalars/ID): ID - The IDs of products to be removed from the combined listing. * [title](/docs/api/admin-graphql/2024-10/scalars/String): String - The updated title for the combined listing. ## Returns * [product](/docs/api/admin-graphql/2024-10/objects/Product): Product The parent product. * [userErrors](/docs/api/admin-graphql/2024-10/objects/CombinedListingUpdateUserError): CombinedListingUpdateUserError! The list of errors that occurred from executing the mutation. ## Examples ### Add child products to a combined listing 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 AddChildProductsToCombinedListing($parentProductId: ID!, $productsAdded: [ChildProductRelationInput!], $optionsAndValues: [OptionAndValueInput!]) { combinedListingUpdate(parentProductId: $parentProductId, productsAdded: $productsAdded, optionsAndValues: $optionsAndValues) { product { id combinedListing { combinedListingChildren(first: 10) { nodes { product { id } parentVariant { selectedOptions { value } } } } } } userErrors { code field message } } }\",\n \"variables\": {\n \"parentProductId\": \"gid://shopify/Product/108828309\",\n \"productsAdded\": [\n {\n \"childProductId\": \"gid://shopify/Product/121709582\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"color\",\n \"value\": \"Blue\"\n },\n {\n \"name\": \"size\",\n \"value\": \"12\"\n }\n ]\n },\n {\n \"childProductId\": \"gid://shopify/Product/912855135\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"color\",\n \"value\": \"Red\"\n },\n {\n \"name\": \"size\",\n \"value\": \"12\"\n }\n ]\n }\n ],\n \"optionsAndValues\": [\n {\n \"name\": \"color\",\n \"values\": [\n \"Blue\",\n \"Red\"\n ]\n },\n {\n \"name\": \"size\",\n \"values\": [\n \"12\"\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 AddChildProductsToCombinedListing($parentProductId: ID!, $productsAdded: [ChildProductRelationInput!], $optionsAndValues: [OptionAndValueInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsAdded: $productsAdded, optionsAndValues: $optionsAndValues) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }`,\n \"variables\": {\n \"parentProductId\": \"gid://shopify/Product/108828309\",\n \"productsAdded\": [\n {\n \"childProductId\": \"gid://shopify/Product/121709582\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"color\",\n \"value\": \"Blue\"\n },\n {\n \"name\": \"size\",\n \"value\": \"12\"\n }\n ]\n },\n {\n \"childProductId\": \"gid://shopify/Product/912855135\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"color\",\n \"value\": \"Red\"\n },\n {\n \"name\": \"size\",\n \"value\": \"12\"\n }\n ]\n }\n ],\n \"optionsAndValues\": [\n {\n \"name\": \"color\",\n \"values\": [\n \"Blue\",\n \"Red\"\n ]\n },\n {\n \"name\": \"size\",\n \"values\": [\n \"12\"\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 AddChildProductsToCombinedListing($parentProductId: ID!, $productsAdded: [ChildProductRelationInput!], $optionsAndValues: [OptionAndValueInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsAdded: $productsAdded, optionsAndValues: $optionsAndValues) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }\nQUERY\n\nvariables = {\n \"parentProductId\": \"gid://shopify/Product/108828309\",\n \"productsAdded\": [{\"childProductId\"=>\"gid://shopify/Product/121709582\", \"selectedParentOptionValues\"=>[{\"name\"=>\"color\", \"value\"=>\"Blue\"}, {\"name\"=>\"size\", \"value\"=>\"12\"}]}, {\"childProductId\"=>\"gid://shopify/Product/912855135\", \"selectedParentOptionValues\"=>[{\"name\"=>\"color\", \"value\"=>\"Red\"}, {\"name\"=>\"size\", \"value\"=>\"12\"}]}],\n \"optionsAndValues\": [{\"name\"=>\"color\", \"values\"=>[\"Blue\", \"Red\"]}, {\"name\"=>\"size\", \"values\"=>[\"12\"]}]\n}\n\nresponse = 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 AddChildProductsToCombinedListing($parentProductId: ID!, $productsAdded: [ChildProductRelationInput!], $optionsAndValues: [OptionAndValueInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsAdded: $productsAdded, optionsAndValues: $optionsAndValues) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }`,\n {\n variables: {\n \"parentProductId\": \"gid://shopify/Product/108828309\",\n \"productsAdded\": [\n {\n \"childProductId\": \"gid://shopify/Product/121709582\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"color\",\n \"value\": \"Blue\"\n },\n {\n \"name\": \"size\",\n \"value\": \"12\"\n }\n ]\n },\n {\n \"childProductId\": \"gid://shopify/Product/912855135\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"color\",\n \"value\": \"Red\"\n },\n {\n \"name\": \"size\",\n \"value\": \"12\"\n }\n ]\n }\n ],\n \"optionsAndValues\": [\n {\n \"name\": \"color\",\n \"values\": [\n \"Blue\",\n \"Red\"\n ]\n },\n {\n \"name\": \"size\",\n \"values\": [\n \"12\"\n ]\n }\n ]\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation AddChildProductsToCombinedListing($parentProductId: ID!, $productsAdded: [ChildProductRelationInput!], $optionsAndValues: [OptionAndValueInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsAdded: $productsAdded, optionsAndValues: $optionsAndValues) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n}" #### Graphql Input { "parentProductId": "gid://shopify/Product/108828309", "productsAdded": [ { "childProductId": "gid://shopify/Product/121709582", "selectedParentOptionValues": [ { "name": "color", "value": "Blue" }, { "name": "size", "value": "12" } ] }, { "childProductId": "gid://shopify/Product/912855135", "selectedParentOptionValues": [ { "name": "color", "value": "Red" }, { "name": "size", "value": "12" } ] } ], "optionsAndValues": [ { "name": "color", "values": [ "Blue", "Red" ] }, { "name": "size", "values": [ "12" ] } ] } #### Graphql Response { "data": { "combinedListingUpdate": { "product": { "id": "gid://shopify/Product/108828309", "combinedListing": { "combinedListingChildren": { "nodes": [ { "product": { "id": "gid://shopify/Product/121709582" }, "parentVariant": { "selectedOptions": [ { "value": "Blue" }, { "value": "12" } ] } }, { "product": { "id": "gid://shopify/Product/912855135" }, "parentVariant": { "selectedOptions": [ { "value": "Red" }, { "value": "12" } ] } } ] } } }, "userErrors": [] } } } ### Remove child products from a combined listing 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 RemoveChildProductsFromCombinedListing($parentProductId: ID!, $productsRemovedIds: [ID!]) { combinedListingUpdate(parentProductId: $parentProductId, productsRemovedIds: $productsRemovedIds) { product { id combinedListing { combinedListingChildren(first: 10) { nodes { product { id } } } } } userErrors { code field message } } }\",\n \"variables\": {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsRemovedIds\": [\n \"gid://shopify/Product/223392616\"\n ]\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation RemoveChildProductsFromCombinedListing($parentProductId: ID!, $productsRemovedIds: [ID!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsRemovedIds: $productsRemovedIds) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }`,\n \"variables\": {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsRemovedIds\": [\n \"gid://shopify/Product/223392616\"\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 RemoveChildProductsFromCombinedListing($parentProductId: ID!, $productsRemovedIds: [ID!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsRemovedIds: $productsRemovedIds) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }\nQUERY\n\nvariables = {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsRemovedIds\": [\"gid://shopify/Product/223392616\"]\n}\n\nresponse = 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 RemoveChildProductsFromCombinedListing($parentProductId: ID!, $productsRemovedIds: [ID!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsRemovedIds: $productsRemovedIds) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }`,\n {\n variables: {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsRemovedIds\": [\n \"gid://shopify/Product/223392616\"\n ]\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation RemoveChildProductsFromCombinedListing($parentProductId: ID!, $productsRemovedIds: [ID!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsRemovedIds: $productsRemovedIds) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n}" #### Graphql Input { "parentProductId": "gid://shopify/Product/362339553", "productsRemovedIds": [ "gid://shopify/Product/223392616" ] } #### Graphql Response { "data": { "combinedListingUpdate": { "product": { "id": "gid://shopify/Product/362339553", "combinedListing": { "combinedListingChildren": { "nodes": [ { "product": { "id": "gid://shopify/Product/555575834" } } ] } } }, "userErrors": [] } } } ### Update option values of combined listing child product 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 UpdateChildProductsOfCombinedListing($parentProductId: ID!, $productsEdited: [ChildProductRelationInput!]) { combinedListingUpdate(parentProductId: $parentProductId, productsEdited: $productsEdited) { product { id combinedListing { combinedListingChildren(first: 10) { nodes { product { id } parentVariant { selectedOptions { value } } } } } } userErrors { code field message } } }\",\n \"variables\": {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsEdited\": [\n {\n \"childProductId\": \"gid://shopify/Product/223392616\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"Color\",\n \"value\": \"green\"\n }\n ]\n },\n {\n \"childProductId\": \"gid://shopify/Product/555575834\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"Color\",\n \"value\": \"blue\"\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 UpdateChildProductsOfCombinedListing($parentProductId: ID!, $productsEdited: [ChildProductRelationInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsEdited: $productsEdited) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }`,\n \"variables\": {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsEdited\": [\n {\n \"childProductId\": \"gid://shopify/Product/223392616\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"Color\",\n \"value\": \"green\"\n }\n ]\n },\n {\n \"childProductId\": \"gid://shopify/Product/555575834\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"Color\",\n \"value\": \"blue\"\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 UpdateChildProductsOfCombinedListing($parentProductId: ID!, $productsEdited: [ChildProductRelationInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsEdited: $productsEdited) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }\nQUERY\n\nvariables = {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsEdited\": [{\"childProductId\"=>\"gid://shopify/Product/223392616\", \"selectedParentOptionValues\"=>[{\"name\"=>\"Color\", \"value\"=>\"green\"}]}, {\"childProductId\"=>\"gid://shopify/Product/555575834\", \"selectedParentOptionValues\"=>[{\"name\"=>\"Color\", \"value\"=>\"blue\"}]}]\n}\n\nresponse = 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 UpdateChildProductsOfCombinedListing($parentProductId: ID!, $productsEdited: [ChildProductRelationInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsEdited: $productsEdited) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n }`,\n {\n variables: {\n \"parentProductId\": \"gid://shopify/Product/362339553\",\n \"productsEdited\": [\n {\n \"childProductId\": \"gid://shopify/Product/223392616\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"Color\",\n \"value\": \"green\"\n }\n ]\n },\n {\n \"childProductId\": \"gid://shopify/Product/555575834\",\n \"selectedParentOptionValues\": [\n {\n \"name\": \"Color\",\n \"value\": \"blue\"\n }\n ]\n }\n ]\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation UpdateChildProductsOfCombinedListing($parentProductId: ID!, $productsEdited: [ChildProductRelationInput!]) {\n combinedListingUpdate(parentProductId: $parentProductId, productsEdited: $productsEdited) {\n product {\n id\n combinedListing {\n combinedListingChildren(first: 10) {\n nodes {\n product {\n id\n }\n parentVariant {\n selectedOptions {\n value\n }\n }\n }\n }\n }\n }\n userErrors {\n code\n field\n message\n }\n }\n}" #### Graphql Input { "parentProductId": "gid://shopify/Product/362339553", "productsEdited": [ { "childProductId": "gid://shopify/Product/223392616", "selectedParentOptionValues": [ { "name": "Color", "value": "green" } ] }, { "childProductId": "gid://shopify/Product/555575834", "selectedParentOptionValues": [ { "name": "Color", "value": "blue" } ] } ] } #### Graphql Response { "data": { "combinedListingUpdate": { "product": { "id": "gid://shopify/Product/362339553", "combinedListing": { "combinedListingChildren": { "nodes": [ { "product": { "id": "gid://shopify/Product/555575834" }, "parentVariant": { "selectedOptions": [ { "value": "blue" } ] } }, { "product": { "id": "gid://shopify/Product/223392616" }, "parentVariant": { "selectedOptions": [ { "value": "green" } ] } } ] } } }, "userErrors": [] } } }