> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ordergroove.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ordergroove.com/_mcp/server.

# Box Subscription Creation on Shopify

Learn how to configure Ordergroove to create bundled subscriptions for multiple line items in a Shopify checkout, including bundle creation, quantity overrides, and product swapping.

By default, Ordergroove will create a **separate subscription** for each line item in a Shopify checkout that has been associated with a selling plan.

If you would like Ordergroove to **bundle** multiple line items in a checkout into a single bundled subscription, you can include a property at the line-item level that we will use to determine which line items are meant to be grouped together.

The property you need to provide at the line-item level is:

`__og_parent_product_id`: the variant ID of the "parent product" you would like the line items to be bundled beneath.

***

## Requirements

* The *parent product* does not need to be present in the cart as a line item itself, **but it must be a real product variant that exists in your Shopify store**. The subscription that is created in Ordergroove will reference this *parent product* at the top level of the subscription for tracking and data-integrity purposes.
* You must still add the required selling plan ID to each line item you want included in the bundle.
* There should only be a single line item in the cart for a given product variant that references a given `__og_parent_product_id`. You should not create carts that have multiple line items for the same product referencing the same `__og_parent_product_id`. For example, the following cart structure **would not** be permitted:

```json
[
  {
    "variant": 12345,
    "__og_parent_product_id": 56789,
    "quantity": 1
  },
  {
    "variant": 12345,
    "__og_parent_product_id": 56789,
    "quantity": 1
  }
]
```

This should instead be represented as:

```json
[
  {
    "variant": 12345,
    "__og_parent_product_id": 56789,
    "quantity": 2
  }
]
```

Here is an example of what the input for this attribute would look like on a product form that is adding products to the customer's cart:

You can also consult Shopify's [cart reference documentation](https://shopify.dev/docs/api/ajax/reference/cart) for information on how this property can be added via API.

Each line item that has `__og_parent_product_id` set to the same variant ID will be bundled into a single subscription in Ordergroove's system after the customer checks out. For example, take a look at this Shopify order:

Notice both the *Tuna Cat Food* and *Chicken Cat Food* products have `__og_parent_product_id` set to the same variant ID. This will cause Ordergroove to create a single subscription that encapsulates both products, and the product set on the subscription itself will be the product variant specified by the `__og_parent_product_id` attribute.

Alternatively, if you would like to create multiple different bundles during the same checkout experience, you should assign to the `__og_parent_product_id` attribute the ID of the parent product concatenated with the separator symbol `:` and a unique key that must be the same for all the products that are supposed to be under the same bundle.

For example, with a parent product of ID `1` and four products with IDs `2`–`5`, where you want 2 different bundles — `{2, 3}` and `{4, 5}` — both using the same parent product, configure the following:

* `{2, 3}`: `__og_parent_product_id = '1:bundle_1'`
* `{4, 5}`: `__og_parent_product_id = '1:bundle_2'`

***

## Overriding Item Quantity

By default, when we create a bundle subscription, the quantity of items in the cart for a bundle item will match the bundle subscription item created in Ordergroove. You can override the quantity of bundle items that will be created for the subscription by sending `__og_subscription_bundle_item_quantity` on the properties of the item.

Here is an example of what the input for this property would look like on a product form that is adding products to the customer's cart:

```html
<input type="hidden" name="properties[__og_subscription_bundle_item_quantity]" value="10">
```

Checking out with an item of quantity 3 but `10` as the overridden quantity in the property will create a bundle subscription in Ordergroove that will ship 10 items instead of the 3 initial ones sent on the checkout order.

***

## Cart Checkout Examples

### Single Bundle

Checking out with these items and line item properties on Shopify:

| Item         | Quantity | Properties                                                         |
| :----------- | :------- | :----------------------------------------------------------------- |
| Banana       | 10       | `name="properties[__og_parent_product_id]" value="{fruit_box_id}"` |
| Orange Juice | 1        | `name="properties[__og_parent_product_id]" value="{fruit_box_id}"` |
| Apple        | 5        | `name="properties[__og_parent_product_id]" value="{fruit_box_id}"` |

Will create this bundle in Ordergroove:

| Subscription Parent Product | Item         | Quantity |
| :-------------------------- | :----------- | :------- |
| `fruit_box_id`              | Banana       | 10       |
| `fruit_box_id`              | Orange Juice | 1        |
| `fruit_box_id`              | Apple        | 5        |

### Multiple Bundles

Checking out with these items and line item properties on Shopify:

| Item         | Quantity | Properties                                                                 |
| :----------- | :------- | :------------------------------------------------------------------------- |
| Banana       | 10       | `name="properties[__og_parent_product_id]" value="{fruit_box_id:bundle1}"` |
| Orange Juice | 1        | `name="properties[__og_parent_product_id]" value="{fruit_box_id:bundle1}"` |
| Apple        | 5        | `name="properties[__og_parent_product_id]" value="{fruit_box_id:bundle1}"` |
| Strawberry   | 2        | `name="properties[__og_parent_product_id]" value="{fruit_box_id:bundle2}"` |
| Grape        | 3        | `name="properties[__og_parent_product_id]" value="{fruit_box_id:bundle2}"` |
| Watermelon   | 1        | `name="properties[__og_parent_product_id]" value="{fruit_box_id:bundle2}"` |

Will create these two bundles in Ordergroove:

**Bundle 1**

| Subscription Parent Product | Item         | Quantity |
| :-------------------------- | :----------- | :------- |
| `fruit_box_id`              | Banana       | 10       |
| `fruit_box_id`              | Orange Juice | 1        |
| `fruit_box_id`              | Apple        | 5        |

**Bundle 2**

| Subscription Parent Product | Item       | Quantity |
| :-------------------------- | :--------- | :------- |
| `fruit_box_id`              | Strawberry | 2        |
| `fruit_box_id`              | Grape      | 3        |
| `fruit_box_id`              | Watermelon | 1        |

***

## Quantity Override Example

When `__og_subscription_bundle_item_quantity` is set alongside `__og_parent_product_id`, the subscription item quantity is overridden for future orders while the checkout order quantity remains unchanged:

| Item         | Quantity | Properties                                                                                    | Checkout Order Qty | Subscription Qty |
| :----------- | :------- | :-------------------------------------------------------------------------------------------- | :----------------- | :--------------- |
| Banana       | 10       | `__og_subscription_bundle_item_quantity=5`<br />`__og_parent_product_id={bundle_product_id}`  | 10                 | 5                |
| Orange Juice | 2        | `__og_parent_product_id={bundle_product_id}`                                                  | 2                  | 2                |
| Apple        | 5        | `__og_subscription_bundle_item_quantity=10`<br />`__og_parent_product_id={bundle_product_id}` | 5                  | 10               |

***

## Product Subscription Swap

The Component Product Swap allows a customer to check out with one product but subscribe to another. To do so, set both `__og_parent_product_id` and `__og_subscription_bundle_item_product_swap` on the line item. The `__og_subscription_bundle_item_product_swap` value should be the product ID of the product you would like to use for the subscription. You cannot swap to a bundle type product.

| Checkout Item | Properties                                                                                                       | Checkout Order Items | Future Subscription Items |
| :------------ | :--------------------------------------------------------------------------------------------------------------- | :------------------- | :------------------------ |
| Banana        | `__og_subscription_bundle_item_product_swap={orange_juice_id}`<br />`__og_parent_product_id={bundle_product_id}` | Banana               | Orange Juice              |

***

## Adding Additional Bundle Items

The `__og_subscription_bundle_item_additions` attribute allows a customer to check out with one product but subscribe to multiple products. Set both `__og_parent_product_id` and `__og_subscription_bundle_item_additions` on the line item. The `__og_subscription_bundle_item_additions` value should be a **stringified** JSON blob consisting of an array of objects, each containing a `product` ID and a `quantity`. Note that additional products cannot be a bundle type.

Input format:

* `__og_parent_product_id`: Set this to the Parent Product ID.
* `__og_subscription_bundle_item_additions`: A stringified JSON blob where each object represents a new product to add to the subscription bundle, with its quantity: `{"product": "<product_id>", "quantity": <quantity>}`.

| Checkout Item | Properties                                                                                                                                                                                   | Checkout Order Items | Future Subscription Items                     |
| :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- | :-------------------------------------------- |
| Banana        | `__og_subscription_bundle_item_additions='[{"product":"{orange_juice_id}","quantity":1},{"product":"{exquisite_apple_id}","quantity":2}]'`<br />`__og_parent_product_id={bundle_product_id}` | Banana               | Banana<br />Orange Juice<br />Exquisite Apple |

***

## Using Multiple Attributes

Attributes can be combined for increased customization:

| Scenario                                                  | Checkout Item | Properties                                                                                                                                                                                                                                                                                                      | Checkout Order | Future Subscription                                            |
| :-------------------------------------------------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- | :------------------------------------------------------------- |
| **Quantity Override and Product Swap**                    | Banana        | `__og_subscription_bundle_item_quantity=5`<br />`__og_subscription_bundle_item_product_swap={orange_juice_id}`<br />`__og_parent_product_id={bundle_product_id}`                                                                                                                                                | Banana - 1     | Orange Juice - 5                                               |
| **Product Swap and Additional Items**                     | Banana        | `__og_subscription_bundle_item_product_swap={orange_juice_id}`<br />`__og_subscription_bundle_item_additions='[{"product":"{grape_juice_id}","quantity":1},{"product":"{exquisite_apple_id}","quantity":2}]'`<br />`__og_parent_product_id={bundle_product_id}`                                                 | Banana - 1     | Orange Juice - 1<br />Grape Juice - 1<br />Exquisite Apple - 2 |
| **Quantity Override, Product Swap, and Additional Items** | Banana        | `__og_subscription_bundle_item_quantity=5`<br />`__og_subscription_bundle_item_product_swap={grape_juice_id}`<br />`__og_subscription_bundle_item_additions='[{"product":"{orange_juice_id}","quantity":1},{"product":"{exquisite_apple_id}","quantity":2}]'`<br />`__og_parent_product_id={bundle_product_id}` | Banana - 1     | Grape Juice - 5<br />Orange Juice - 1<br />Exquisite Apple - 2 |