Introduction

Chord's OMS platform supports two methods of selling a collection of products under a single price: 1. Kit (static bundle) 2. Bundle (dynamic bundle) This document will review these two options to choose your best action.

What are kits?

A kit is a **pre-selected, fixed collection of products under a single SKU**. Your customer cannot modify the products within a kit. However, you can create multiple kits which contain all the combinations of products they wish to sell.

When a kit product is synced to the OMS, it creates multiple variants by permuting all possible combinations of these same variants for the products within the kit.

For example, consider a kit called Plants that consists of three products and their variants:

The OMS will generate a product called **Plants** with the following variants: 1. plant-1-large|plant-2-red|plant-3 2. plant-1-large|plant-2-green|plant-3 3. plant-1-small|plant-2-red|plant-3 4. plant-1-small|plant-2-green|plant-3 The master SKU for the kit product is the combined SKUs of all parts separated by pipes. Using the example above, the Plants kit will have a master SKU of plant-1|plant-2|plant-3.

Create a kit

1. In the CMS, create a new entry of type Kit.
2. Set the store variable SYNC_SKU_BASED_BUNDLES to enabled. When OMS syncs the kits and bundles with the CMS, it will set the SKU of the bundle to the permutation of all products in the kit.

What are bundles?

A bundle is a dynamically selected collection of products. The products within a bundle are not pre-defined within OMS like they are with kits. Instead, customers who add a bundle to their cart may then choose from a collection of variants (called parts) to add to the bundle.

A store can define what parts are within a bundle through the front end and prevent users from changing the bundle's contents. In this manner, a bundle can behave similarly to a kit without requiring OMS to create and manage multiple variants. 

This is useful if your store offers large numbers of possible parts within a bundle. Imagine maintaining distinct variants for every single combination of colors that a child can select in a pack of crayons.

The bundle has a single price regardless of which parts a customer adds. However, you can choose which parts may be added to a bundle.

A bundle is comprised of multiple parts. A part can be a product (including all its variants) or a specific variant.

Create a bundle

In Contentful, create a new Content Model named Bundle.

Click on Add Content Type



Name your new entry Bundle, and click Create.





Click Add field



Add the following fields.





Click on the Content tab and select Bundle in the dropdown, click Add Entry and individually add each Product that is part of the bundle.





Once done, Publish your entries.





Data model

Product

A boolean bundle was added to the Product model to denote whether or not the product is a singular product or a bundle of products.

For example, the following products are bundles and will have bundle: true:

BundlesPart

Used to define and validate what products may be added to a specific bundle. It also defines the maximum quantity of parts allowed within the bundle.

For example, consider the bundles defined above:

API

Add a Bundle to the Cart

To add a bundle to the cart, the app calls POST /api/orders/{order_number}/line_items. The payload will include the sku, variant_id, and id of the bundle, along with the list of variants to include in the bundle within the parts array. Note that the parts array is within the options object.

The payload for adding a bundle to your cart:

x{
   "line_item":{
      "sku":"KIT-1",
      "quantity":1,
      "options":{
         "parts":[
            {
               "sku":"PART-1",
               "quantity":1
            },
            {
               "sku":"PART-2",
               "quantity":1
            }
         ]
      }
   }
}

The line_items array in the order response will look like this:

"line_items":[
	{
		"id":159,
		"quantity":1,
		"price":"65.0",
		"variant_id":329,
		"variant":{
		  "id":329,
		  "name":"Starter Kit",
		  "sku":"KIT",
		},
		"is_bundle":true,
		"parts":[
		  {
		     "id":170,
		     "sku":"PART-1",
		     "quantity":1
		  },
		  {
		     "id":171,
		     "sku":"PART-2",
		     "quantity":1
		  }
		]
	}
]

Updating/Removing Parts from a Cart

Once a bundle is in a cart, parts can be added or removed using the /api/orders/{order_number}/line_items/{line_item_number}endpoint, where the line_item_number is the ID of the line item for the bundle.

The payload is:

{
	line_item: {
		id: 1,
		part_line_items: [
			{
				id: 1
				sku: 'sku-1',
				_destroy: true
			}
		]
	}
}

Misc Code Notes



Parts in the API payload are converted to part_line_item_attributes hash in the normalize_part_params method. The part_line_item_attributes hash is attached to the line_item_attributes in the options array.

The part_line_item is created when the line_item is created in the Spree::OrderContents#after_add_or_removemethod. Uses some Rails magic to instantiate the part_line_item.