1. Product catalogs

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
  • 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

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

If you have suggestions for improving this article, let us know!