Product associations

Important

The GraphQL API for Product Associations is currently in Preview status for customers on the AWS-US cluster. For more information, see GraphQL API policy.

Product associations establish links between editions of products, in order to represent the dependencies between them. Only marketplace owners with the Marketplace Manager role can create them.

A product association applies purchase rules so that when a customer buys a given product edition, they must also buy other product editions with which it is associated. When a product edition is included in the cart during checkout, the cart indicates any dependencies it has on other products, and the checkout cannot proceed unless those products are also included in the cart.

The simplest example of a product association is an add-on: a product that supplements another parent product. For example, an add-on could be reporting software that tracks activity in a specific database management product—a customer must have the database management product in order to use the reporting software, so it's important that they buy it at the same time as the add-on.

You can use product associations to create more detailed product linkages:

• Multiple products—You can create an association that links a product edition with several other products or product editions at a time.

  For example, if you offer a desktop computer, you can create a product association such that customers must also purchase an operating system and monitor at the same time.

• Alternative choices—You can specify that a product edition requires only one choice from a list of other products or product editions.

  For example, you can specify that customers who buy a desktop computer must have an operating system to go with it, but may choose one of two different operating systems.

• Layers of associations—You can create a hierarchy of associations, where a product edition may be associated with a second product that itself is associated with a third product.

  For example, you can specify that customers who buy a special access keyboard can only buy it for a specific model of desktop with which it is compatible. That desktop in turn may require purchase of an operating system.

By combining these aspects of product associations, you can create linkages that are as complex as you need them to be to ensure that end customers are able to complete their purchases.

Working with product associations

You can create product associations between editions of products that have been published on the marketplace. For information on how to create and publish a product through the marketplace UI, see the Products section of the online help.

You can also create a product using the GraphQL APIs. This method has the advantage of returning the id values for products and editions as you create them, so you can note them down for use when you create the product associations. For information on how to create a product using GraphQL APIs, see the Product management guide section.

The product editions involved in a product association must already be published on the marketplace. You cannot create product associations for product editions that are still being worked on in the staging catalog; they must be complete, and available for purchase on the marketplace.

It is up to you to decide how you want to structure your product associations. The product association mechanism is very flexible, so you can use it to define all sorts of product relationships. These relationships can be as simple or as complex as you need.

Note that a given product association only goes one way, establishing that purchasing the given product edition requires one or more other product editions. This does not mean that those other products in turn require the product edition that requires them; to establish such a relationship, you must define a matching product association on each of those other product editions.

Product association APIs

To use any of the GraphQL APIs for product associations, you must have the id attributes of the products and editions to be involved. If you do not have these values already, you can retrieve them by using the products query:

• products—Lists the attributes of all products and their editions.

There are two GraphQL API mutations that you can use to affect product associations:

• createProductEditionAssociations—Creates product associations between a specific edition of a product, and editions of other products.

• deleteProductEditionAssociation—Removes a specific product association between an edition and other product editions.

Notice that there is no separate API call for updating a product association. If you want to add or subtract from the products that a given product edition is associated with, you can only do so by deleting the existing product association, and creating a new product association that includes the new dependencies.

Within the ProductEdition object, there is also a query you can use to retrieve the product associations of a given ProductEdition, listing all the other ProductEditions with which it is linked.

• ProductEdition.upstreamAssociations—Lists all product associations that the edition has to editions of other products that it requires.

This query automatically uses the id values associated with the ProductEdition (the product id and edition id).