# combinedListingUpdate - admin - MUTATION
Version: 2024-07
## 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/2024-07/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/2024-07/scalars/ID): ID! - The ID of the parent product.
* [productsAdded](/docs/api/admin/2024-07/input-objects/ChildProductRelationInput): ChildProductRelationInput - The child products to add and their assigned options and option values.
* [productsEdited](/docs/api/admin/2024-07/input-objects/ChildProductRelationInput): ChildProductRelationInput - The child products to edit and their assigned options and option values.
* [productsRemovedIds](/docs/api/admin/2024-07/scalars/ID): ID - The IDs of products to be removed from the combined listing.
* [title](/docs/api/admin/2024-07/scalars/String): String - The updated title for the combined listing.
## Returns
* [product](/docs/api/admin/2024-07/objects/Product): Product The parent product.
* [userErrors](/docs/api/admin/2024-07/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-07/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-07/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-07/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": []
}
}
}