---
title: Product bundles
slug: product-bundles
abstract: Product bundles enable selling multiple products together with customized pricing, quantity requirements, and flexible configurations.
content_type: concept
audience: \[business-user, architect, developer]
---
# Product bundles

Product bundles enable selling multiple products together with customized pricing, quantity requirements, and flexible configurations. This feature supports various e-commerce scenarios from simple product groupings to complex package configurations.

## Common use cases

### Employee uniforms

- Bundle multiple uniform items
- Apply package discounts
- Set minimum quantities
- Ensure complete sets

### Complementary products

- Group related items
- Offer package pricing
- Encourage cross-selling
- Simplify purchasing

### Equipment packages

- Bundle main products with accessories
- Include required components
- Offer optional additions
- Streamline selection

## Core features

### Bundle visibility

- Appears in product lists
- Filter with `BundleID={id}`
- Follows [product visibility rules](https://doc.sitecore.com/ordercloud/en/developers/platform/product-visibility.html)
- Requires visible component products

### Assignment flexibility

- Catalog assignments
- Category placement
- Party-specific availability
- Granular control

### Pricing structure

- Individual product pricing
- Tax calculation support
- Bundle-specific rates
- Flexible discounting

### Order management

- Single API call creation
- Component management
- Quantity control
- Validation rules

## Product properties

### Product.IsBundle

Read-only flag that:

- Identifies bundle products
- Enables list visibility
- Prevents single-item orders
- Supports filtering (`IsBundle=false`)

### LineItem.IsBundle

Read-only indicator for:

- Bundle order items
- Zero unit pricing
- Order count exclusion
- Bundle identification

### LineItem.BundleItemID

Reference field providing:

- Bundle line item links
- Purchase identification
- UI grouping support
- Order management

### PriceBreak.BundlePrice

Price determination with priority:

1. BundlePrice: Bundle-specific rate
2. SubscriptionPrice: For subscription orders
3. SalePrice: Active sale pricing
4. Price: Standard pricing

## Bundle resource

Core bundle definition:

```json
{
  "ID": "",
  "OwnerID": "",
  "Name": "",
  "Description": "",
  "Active": true,
  "xp": {}
}
```

Important: Maintain consistent xp schemas between bundles and products to prevent indexing issues.

## Security roles

Access control through:

- BundleReader: View access
- BundleAdmin: Full management
- BundleAssignmentAdmin: Assignment control

## API endpoints

### Bundle management

Core operations:

- `GET v1/bundles`
- `GET v1/bundles/{bundleID}`
- `POST v1/bundles`
- `PUT v1/bundles/{bundleID}`
- `PATCH v1/bundles/{bundleID}`
- `DELETE v1/bundles/{bundleID}`

## Assignment management

### Catalog assignments

Structure:

```json
{
  "CatalogID": "",
  "BundleID": ""
}
```

Operations:

- `GET v1/catalogs/bundleassignments`
- `POST v1/catalogs/bundleassignments`
- `DELETE v1/catalogs/{catalogID}/bundleassignments/{bundleID}`

### Category assignments

Structure:

```json
{
  "CategoryID": "",
  "BundleID": "",
  "ListOrder": 0
}
```

Operations:

- `GET v1/catalogs/{catalogID}/categories/bundleassignments`
- `POST v1/catalogs/{catalogID}/categories/bundleassignments`
- `DELETE v1/catalogs/{catalogID}/categories/{categoryID}/bundleassignments/{bundleID}`

### Product assignments

Structure:

```json
{
  "BundleID": "",
  "ProductID": "",
  "Required": true,
  "DefaultQuantity": null
}
```

Operations:

- `GET v1/bundles/productassignments`
- `POST v1/bundles/productassignments`
- `DELETE v1/bundles/{bundleID}/productassignments/{productID}`

### Party assignments

Structure:

```json
{
  "SellerID": "",
  "BundleID": "",
  "BuyerID": "",
  "UserGroupID": ""
}
```

Operations:

- `GET v1/bundles/assignments`
- `POST v1/bundles/assignments`
- `DELETE v1/bundles/{bundleID}/assignments/{buyerID}`

## Order management

### Bundle order structure

Creates multiple items:

- Bundle representation item
- Component product items
- Inter-item references
- Price allocations

### Bundle operations

Adding bundles:

- `POST v1/orders/{direction}/{orderID}/bundles/{bundleID}`
- `POST v1/cart/bundles/{bundleID}`

Configuration options:

- Optional line item specifications
- Default quantity handling
- Required product validation
- Parent product handling
- Required spec validation
- Custom validation via [pre-webhooks](https://doc.sitecore.com/ordercloud/en/developers/platform/webhooks.html#pre-hook-responses)

Example validation:

- Optional shorts and socks in uniform bundle
- Require socks if shorts selected
- Enforce package completeness
- Validate configurations

Removing bundles:

- `DELETE v1/orders/{direction}/{orderID}/bundles/{bundleID}/{bundleItemID}`
- `DELETE v1/cart/bundles/{bundleID}/{bundleItemID}`

Item management:

- Update operations:

  ```
  PATCH v1/orders/{direction}/{orderID}/lineitems/{itemID}
  PUT v1/orders/{direction}/{orderID}/lineitems/{itemID}
  PATCH v1/cart/lineitems/{itemID}
  PUT v1/cart/lineitems/{itemID}
  ```

- Delete operations:

  ```
  DELETE v1/orders/{direction}/{orderID}/lineitems/{itemID}
  DELETE v1/cart/lineitems/{itemID}
  ```

Important: Cannot delete required bundle items.

## Implementation example

### Scenario

Creating a three-product bundle with:

- Existing price schedules
- Catalog visibility
- Custom bundle pricing

### Administrative setup

1. Configure pricing:

   ```
   PATCH v1/priceschedules/{priceScheduleID}
   ```

   Set bundle-specific prices

2. Create bundle:

   ```
   POST v1/bundles
   ```

   Define bundle structure

3. Set catalog placement:

   ```
   POST v1/catalogs/bundleassignments
   POST v1/catalogs/{catalogID}/categories/bundleassignments
   ```

4. Configure products:

   ```
   POST v1/bundles/productassignments
   ```

   Specify requirements

5. Manage access:

   ```
   POST v1/bundles/assignments
   ```

   Control visibility

### Shopper experience

1. Bundle discovery:

   ```
   GET v1/me/products
   ```

   View available bundles

2. Bundle examination:

   ```
   GET v1/me/products?BundleID={id}
   ```

   Review components and pricing

3. Purchase initiation:

   ```
   POST v1/cart/bundles/{bundleID}
   ```

   Add to cart


## Bundle products for enhanced commerce experiences


Product bundling provides strategic sales opportunities beyond simple product grouping. This feature enables:

### Business capabilities

1. Product promotion:
   - Cross-product marketing
   - New product discovery
   - Complementary product sales

2. Pricing strategies:
   - Bundle discounts
   - Volume pricing
   - Inventory management

3. Customer experience:
   - Guided purchasing
   - Product compatibility
   - Customization options

### Implementation examples

#### Multi-buyer pricing bundles

Bundle pricing strategies can incorporate:

- Group-specific discounts
- Volume incentives
- Targeted promotions

Example: Appliance retailer humidifier bundle

1. Consumer pricing (B2C):
   - Individual: $160 ($140 humidifier + $20 filter)
   - Bundle: $125 ($120 humidifier + $5 filter)

2. Business pricing (B2B):
   - Business 1 bundle: $98 vs. $116 individual
   - Business 2 bundle: $104 vs. $133 individual

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/196d56a1a2084d7ea66975b699b3b544-2.png)

Implementation note: Bundle pricing applies to individual items to accommodate:

- Different tax codes
- Item-specific calculations
- Flexible pricing structures

For configuration details, see [Price Schedules](https://api-docs.sitecore.com/ordercloud/price-schedules/priceschedules.create).

#### Guided ordering implementation

Bundles can structure purchasing workflows:

Example: Remote workstation equipment bundles

![ ](https://doc.sitecore.com/api/markdown-image/ordercloud/en/developers/platform/images/00a625b7ea3a4342b52405d52f8ff3e2.png)

Department-specific configurations:

1. Standard bundle:
   - Required: Laptop, keyboard
   - Optional: Monitors (0-2), mice (0-2), headsets (0-2)

2. Marketing bundle:
   - Includes standard items
   - Additional: Microphone option

3. Sales bundle:
   - Required: Mobile phone
   - Optional: Home printer
   - Includes standard items

Configuration options:

- Required/optional items via [Product-Bundle assignment](https://api-docs.sitecore.com/ordercloud/bundles/bundles.saveproductassignment)
- Quantity limits through Price Schedule settings
- Department-specific customization

#### Subscription bundle implementation

Bundle integration with subscription services:

Example: Meal kit service

1. Bundle options:
   - 2 meals/week
   - 3 meals/week
   - 4 meals/week

2. Subscription features:
   - Volume-based pricing
   - Automated ordering
   - Flexible meal selection

Implementation using [Bundle Subscription](https://api-docs.sitecore.com/ordercloud/bundle-subscription-items) endpoints enables:

- Recurring orders
- Bundle pricing
- Customer customization

### Implementation strategies

Effective bundle usage:

1. Product dependencies:
   - Ensure compatibility
   - Simplify selection
   - Improve customer experience

2. Marketing objectives:
   - Gift bundling
   - Promotional pricing
   - Inventory management

3. Customer benefits:
   - Simplified purchasing
   - Cost savings
   - Product discovery

## Related reading

- [Introducing order returns](https://doc.sitecore.com/ordercloud/en/developers/platform/order-returns.html)
- [Cart](https://doc.sitecore.com/ordercloud/en/developers/platform/cart.html)