> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commerce.jolly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Groups

> How Rye combines a merchant's single-color products into one listing in your catalog, and how to order a variant from that listing.

Some merchants publish each color of a model as a separate product. A **product group** combines those products into one listing in your catalog. Each product in the group becomes one variant of the listing.

> [!NOTE]
>
> Product groups apply only to catalogs that Rye syncs into your own product system. The [product
> lookup endpoint](https://docs.commerce.jolly.dev/api-v2/api-reference/products/lookup-product.md) and the [`product.updated`
> webhook](https://docs.commerce.jolly.dev/api-v2/webhooks/types#products) still return each merchant product on its own. [Contact
> us](https://docs.commerce.jolly.dev/api-v2/support.md) to set up a group.

## Example of a product group

A merchant sells one record stand in 3 colors, as 3 separate Shopify products:

| Merchant product | Shopify options |
| - | - |
| LP Record Stand - Cobalt | `Title: Default Title` |
| LP Record Stand - Olive | `Title: Default Title` |
| LP Record Stand - Brick Red | `Title: Default Title` |

Without a group, your catalog gets 3 listings. With a group titled `LP Record Stand` and the option `Color`, your catalog gets 1 listing with 3 variants: `Color: Cobalt`, `Color: Olive`, and `Color: Brick Red`.

## How a group maps to the synced listing

| Field | Value for a grouped listing |
| - | - |
| Listing ID | `group:<group id>`, for example `group:lp-record-stand` |
| Title | The group title |
| Option | 1 option, named by the group, for example `Color` |
| Variant option value | The label of the member product, for example `Cobalt` |
| Variant SKU | `group:<group id>:<Shopify variant ID>`. The SKU is new, so it never matches a SKU on a standalone listing. |
| Variant product URL | The URL of the member product, with `?variant=<Shopify variant ID>` |
| Images | The images of every member product, featured images first, with duplicates removed |
| Price and stock | The price and stock of each member product. They update when the merchant changes them. |

## Order a variant from a grouped listing

Create the checkout intent with the variant product URL of the variant that the buyer picked. Don't send `variantSelections`.

```json theme={null}
{
  "productUrl": "https://www.whatsupton.com/products/lp-record-stand-cobalt?variant=48432570204372",
  "quantity": 1,
  "buyer": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "212-333-2121",
    "address1": "123 Main St",
    "address2": "Apt 1",
    "city": "New York",
    "province": "NY",
    "postalCode": "10001",
    "country": "US"
  }
}
```

> [!WARNING]
>
> Don't send `variantSelections` for a variant of a grouped listing. If you send the group option,
> for example `Color: Cobalt`, the checkout intent fails with `variant_selections_invalid`.

Rye matches `variantSelections` against the options of the product at `productUrl`, and the selections take precedence over the variant in the URL. Each member product has only its own options, usually `Title: Default Title`. The group option exists only on your listing, so it doesn't match. See [Variants](https://docs.commerce.jolly.dev/api-v2/variants.md) for how Rye resolves variants.

## When a group goes live

Rye switches a group on at a time that you agree with us, because the switch removes the standalone listings:

1. Rye publishes the grouped listing.
2. Rye deactivates the standalone listing of each member product. Each color is then sold only as a variant of the grouped listing.
3. Move any merchandising that points at the standalone listings to the grouped listing.

## Updates after a group is live

* A change to any member product, such as its price, stock, or images, republishes the whole grouped listing.
* If the merchant removes a member product, Rye deactivates its standalone listing and removes its variant from the grouped listing.
* If no member products are left, Rye deactivates the grouped listing.
* If a member product has more than 1 variant, Rye leaves it out of the grouped listing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.