Create a combined listing

In this tutorial, you'll learn how to do the following tasks:

• Use the GraphQL Admin API to create a parent product
• Add child products to the combined listing
• Query all combined listings
• Add a child product to an existing combined listing
• Remove a child product from an existing combined listing
• Change the option value of a child product in an existing combined listing
• Combine adding, editing, and removing child products into one mutation

We're going to do that by creating a combined listing for a pair of shorts that come in four different colors. The combined listing will have a parent product that represents the shorts and four child products that represent each of the colors.

• You've created an app on your development store.
• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the write_products access scope. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
• Your app uses the unstable GraphQL API for the products type, and the productCreate and combinedListingUpdate mutations.
• The store has access to the feature. You can request early access by reaching out to Partner support.
• You already have products in your store that you want to combine.

A combined listing is modeled on a single parent product that has variants that point to one or more child products using the CombinedListingRole type and the combinedListingUpdate mutation.

Creating a combined listing starts with creating a parent product. You'll use the productCreate mutation to create that combined listing.

For the shorts, you'll create a new product called "Shorts" with a combinedListingRole of PARENT. This creates the parent product, but does not yet associate the child products. You'll associate child products in a subsequent step.

With the combined listing created, you'll add the child products to the combined listing using the combinedListingUpdate mutation.

For the child products you already have, you'll need to get their IDs to add them to the parent product that you created.

After creating a combined listings, you can use the products query to retrieve only combined listing parents and their children. With this, you can pull just the Shorts parent product and its children.

Your team has come up with a new color of Shorts and you want to add it to the combined listing so your customers can easily buy it. You can do that by using the same mutation you used to add child products earlier and add the new child product to the productsAdded field for the combinedListingUpdate mutation.

By default, new colors are added to the end of the parent product's option values. Alternatively, you can supply optionsAndValues to change the order of both options and option values. We'll do that here to put your new pink shorts at the front of the color option.

Later, you decide to stop selling the orange shorts. You can remove the orange shorts by using the productsRemovedIds argument for the combinedListingUpdate mutation.

As part of a larger change the team decides to change the option value "Blue" to "Navy", this isn't a new product, but just a name change. In that case, we want to modify the name of the color option value while using the same product. You'll need to update the name of the child product separately, but you'll also want to modify the color option value on the parent product. You can do that by using the productsEdited argument on the combinedListingUpdate mutation.

You can combine adding child products, changing options and option values on existing child products, and removing child products into a single mutation. With a single mutation you save time compared to sending multiple mutations.

• Learn more about the combinedListingUpdate mutation.