# Create a new Build-A-Box subscription bundle

Creates a new subscription bundle (Build-A-Box) allowing customers to select and customize products for recurring deliveries. Build-A-Box enables a flexible subscription model where customers can create personalized product boxes.

What is Build-A-Box?
Build-A-Box is a subscription feature that allows customers to curate their own product bundles by selecting from a predefined set of products. This creates a highly personalized subscription experience where customers have full control over what they receive in each delivery cycle.

Key Features:
- Product Selection: Customers choose which products to include in their box
- Quantity Control: Set minimum and maximum product quantities
- Flexible Configuration: Define rules for product combinations
- Pricing Models: Support for various pricing strategies (per-item, flat rate, tiered)
- Recurring Delivery: Automatic fulfillment based on subscription frequency
- Customization Options: Allow product swaps between delivery cycles

Configuration Options:
- Bundle Settings:
  - Bundle name and description
  - Unique handle for identification
  - Product pool (available products for selection)
  - Minimum/maximum number of products
  - Product quantity limits

- Pricing Configuration:
  - Pricing type (per-product, flat rate, or tiered)
  - Discount rules
  - Promotional pricing
  - Currency settings

- Delivery Options:
  - Subscription frequencies (weekly, bi-weekly, monthly, etc.)
  - Delivery intervals
  - Cut-off times for order modifications
  - Shipping methods

- Rules and Restrictions:
  - Product combination rules
  - Category restrictions
  - Inventory requirements
  - Customer eligibility criteria

Build-A-Box Types:
1. Open Selection: Customers can choose any products from the available pool
2. Category-Based: Products are organized into categories with selection rules
3. Single Product: Customers select variations of a single product type
4. Tiered Boxes: Different box sizes with varying product counts and pricing

Use Cases:
- Coffee Subscription: Customers select different coffee blends for monthly delivery
- Snack Boxes: Build custom snack boxes from a variety of treats
- Beauty Boxes: Choose skincare and makeup products based on preferences
- Meal Kits: Select recipes and ingredients for weekly meal planning
- Pet Supply Boxes: Customize toys, treats, and supplies for pets
- Supplement Subscriptions: Create personalized vitamin and supplement regimens

Customer Workflow:
1. Customer discovers Build-A-Box offering
2. Selects products from available options
3. Chooses delivery frequency
4. Reviews pricing and discounts
5. Completes subscription signup
6. Receives recurring deliveries
7. Can modify selections between delivery cycles

Important Notes:
- Each bundle must have a unique handle for identification
- Product availability is validated at creation time
- Pricing rules are applied based on bundle configuration
- Bundles must be associated with at least one subscription frequency
- Inventory levels should be checked for all included products
- Bundle status (active/inactive) controls customer visibility

Best Practices:
- Set clear minimum and maximum product limits
- Provide detailed product descriptions and images
- Configure appropriate pricing that encourages subscriptions
- Offer multiple delivery frequency options
- Set reasonable inventory thresholds
- Enable customer portal access for subscription management
- Test bundle configurations before making them live

Authentication: Requires valid X-API-Key header or api_key parameter (deprecated)

Endpoint: POST /api/external/v2/build-a-box
Version: 0.0.1

## Query parameters:

  - `api_key` (string)
    API Key (Deprecated - Use Header X-API-Key instead)

## Header parameters:

  - `X-API-Key` (string)

## Request fields (application/json):

  - `id` (integer)

  - `shop` (string, required)

  - `subscriptionBundlingEnabled` (boolean)

  - `subscriptionId` (integer)

  - `minProductCount` (integer)

  - `maxProductCount` (integer)

  - `discount` (number)

  - `uniqueRef` (string)

  - `groupName` (string)

  - `subscriptionBundleLink` (string)

  - `bundleRedirect` (string)
    Enum: "CART", "CHECKOUT", "CUSTOM", "NONE"

  - `customRedirectURL` (string)

  - `minOrderAmount` (number)

  - `tieredDiscount` (string)

  - `productViewStyle` (string)
    Enum: "QUICK_ADD", "VIEW_DETAILS"

  - `buildABoxType` (string)
    Enum: "CLASSIC", "SINGLE_PRODUCT", "MIX_AND_MATCH", "INFINITE", "CUSTOMIZE_BUNDLE", "CLASSIC_BUILD_A_BOX", "SINGLE_PRODUCT_BUILD_A_BOX", "VOLUME_DISCOUNT", "DISCOUNTED_PRICING", "SHIPPING_DISCOUNT", "BUY_X_GET_Y", "SECTIONED_BUNDLE"

  - `singleProductSettings` (string)

  - `subscriptionGroup` (string)

  - `bundleTopHtml` (string)

  - `bundleBottomHtml` (string)

  - `proceedToCheckoutButtonText` (string)

  - `chooseProductsText` (string)

  - `name` (string)

  - `trackInventory` (boolean)

  - `allowOneTimePurchase` (boolean)

  - `thirdPartyRule` (boolean)

  - `selectionType` (string)
    Enum: "FIXED", "FLEXIBLE"

  - `variants` (string)

  - `discountedVariants` (string)

  - `sections` (string)

  - `appliesOn` (string)
    Enum: "PRODUCT", "COLLECTION", "BOTH", "ONE_TIME", "SUBSCRIPTION"

  - `productDiscountType` (string)
    Enum: "SELECTED_PRODUCT", "EACH_PRODUCT"

  - `collectionData` (string)

  - `productSelectionType` (string)
    Enum: "PRODUCT", "COLLECTION"

  - `sellingPlanIds` (string)

  - `minUniqueProductCheck` (boolean)

## Response 201 fields (application/json):

  - `id` (integer)

  - `shop` (string, required)

  - `subscriptionBundlingEnabled` (boolean)

  - `subscriptionId` (integer)

  - `minProductCount` (integer)

  - `maxProductCount` (integer)

  - `discount` (number)

  - `uniqueRef` (string)

  - `groupName` (string)

  - `subscriptionBundleLink` (string)

  - `bundleRedirect` (string)
    Enum: "CART", "CHECKOUT", "CUSTOM", "NONE"

  - `customRedirectURL` (string)

  - `minOrderAmount` (number)

  - `tieredDiscount` (string)

  - `productViewStyle` (string)
    Enum: "QUICK_ADD", "VIEW_DETAILS"

  - `buildABoxType` (string)
    Enum: "CLASSIC", "SINGLE_PRODUCT", "MIX_AND_MATCH", "INFINITE", "CUSTOMIZE_BUNDLE", "CLASSIC_BUILD_A_BOX", "SINGLE_PRODUCT_BUILD_A_BOX", "VOLUME_DISCOUNT", "DISCOUNTED_PRICING", "SHIPPING_DISCOUNT", "BUY_X_GET_Y", "SECTIONED_BUNDLE"

  - `singleProductSettings` (string)

  - `subscriptionGroup` (string)

  - `bundleTopHtml` (string)

  - `bundleBottomHtml` (string)

  - `proceedToCheckoutButtonText` (string)

  - `chooseProductsText` (string)

  - `name` (string)

  - `trackInventory` (boolean)

  - `allowOneTimePurchase` (boolean)

  - `thirdPartyRule` (boolean)

  - `selectionType` (string)
    Enum: "FIXED", "FLEXIBLE"

  - `variants` (string)

  - `discountedVariants` (string)

  - `sections` (string)

  - `appliesOn` (string)
    Enum: "PRODUCT", "COLLECTION", "BOTH", "ONE_TIME", "SUBSCRIPTION"

  - `productDiscountType` (string)
    Enum: "SELECTED_PRODUCT", "EACH_PRODUCT"

  - `collectionData` (string)

  - `productSelectionType` (string)
    Enum: "PRODUCT", "COLLECTION"

  - `sellingPlanIds` (string)

  - `minUniqueProductCheck` (boolean)


## Response 400 fields

## Response 401 fields

## Response 403 fields

## Response 422 fields

## Response 500 fields