# Retrieve Build-A-Box bundle details by handle for customer storefront

Fetches comprehensive Build-A-Box bundle configuration using a user-friendly handle (URL slug) instead of numeric ID. This endpoint is specifically designed for customer-facing storefronts and integration scenarios where you want to reference bundles by their human-readable handles rather than database IDs.

Key Differences from GET /{id}:
- Lookup Method: Uses bundle handle (e.g., 'premium-coffee-box') instead of numeric ID (e.g., 12345)
- Response Format: Returns SubscriptionBundlingResponseV3 with enhanced structure
- Customer Focus: Optimized for storefront display and customer selection workflows
- Bundle + Subscription: Returns both bundle details AND associated subscription plan information
- Public Access: Designed for integration in customer-facing applications

What is a Bundle Handle?
A handle is a URL-friendly identifier for a bundle:
- Format: lowercase letters, numbers, and hyphens only
- Example: premium-coffee-selection, monthly-snack-box, beauty-essentials
- Stable: Unlike IDs, handles remain consistent across environments
- SEO-Friendly: Can be used in customer-facing URLs
- Human-Readable: Easy to remember and communicate

Response Structure (SubscriptionBundlingResponseV3):
json
{
  "bundle": {           // Complete bundle configuration
    "id": 45678,
    "bundleName": "Premium Coffee Selection",
    "bundleHandle": "premium-coffee-selection",
    "description": "...",
    "products": [...],
    "pricing": {...},
    "active": true
  },
  "subscription": {     // Associated subscription plan details
    "planId": 98765,
    "frequencies": [...],
    "deliveryOptions": {...},
    "sellingPlan": {...}
  }
}


Primary Use Cases:
1. Storefront Integration: Display bundle details on product pages
2. Customer Portal: Allow customers to browse available bundles
3. Landing Pages: Create dedicated pages for specific bundles using handles
4. Marketing Campaigns: Link directly to bundles with memorable URLs
5. Cross-Platform Sync: Use stable handles for multi-platform integrations
6. Mobile Apps: Retrieve bundle data using consistent identifiers
7. External Integrations: Third-party systems can reference bundles by handle

When to Use Handle vs ID:
- Use Handle when:
  - Building customer-facing features
  - Creating shareable URLs
  - Syncing across environments (dev → staging → prod)
  - External systems need stable references
  - SEO and user experience are priorities

- Use ID when:
  - You already have the numeric ID from another API response
  - Performing administrative operations
  - Internal system integration
  - Optimizing for query performance

Availability Validation:
The endpoint validates that:
- Bundle exists and belongs to the specified shop
- Bundle has an associated subscription configuration
- If validation fails, returns 404 Not Found
- Both bundle AND subscription must be present for success response

Integration Examples:
Storefront Display:
javascript
// Fetch bundle for display on product page
const handle = 'premium-coffee-selection';
const response = await fetch(
  /api/external/v2/build-a-box/${handle},
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { bundle, subscription } = await response.json();
displayBundleOptions(bundle, subscription);


Best Practices:
- Handle Naming: Use descriptive, SEO-friendly handles
- Caching: Cache bundle data with handle as key for better performance
- Error Handling: Always check for 404 - bundle may be deleted or deactivated
- Environment Sync: Use handles to maintain consistency across environments
- URL Structure: Incorporate handles into clean, readable URLs
- Documentation: Document handle conventions for your team

Performance Considerations:
- Handle lookups may be slightly slower than ID lookups
- Response includes full bundle + subscription data (larger payload)
- Consider caching for frequently accessed bundles
- Returns complete product catalog for the bundle

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

Endpoint: GET /api/external/v2/build-a-box/{handle}
Version: 0.0.1

## Path parameters:

  - `handle` (string, required)
    Bundle Handle

## Query parameters:

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

## Header parameters:

  - `X-API-Key` (string)

## Response 200 fields (application/json):

  - `bundle` (object)

  - `bundle.id` (integer)

  - `bundle.shop` (string, required)

  - `bundle.subscriptionBundlingEnabled` (boolean)

  - `bundle.subscriptionId` (integer)

  - `bundle.minProductCount` (integer)

  - `bundle.maxProductCount` (integer)

  - `bundle.discount` (number)

  - `bundle.uniqueRef` (string)

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

  - `bundle.customRedirectURL` (string)

  - `bundle.minOrderAmount` (number)

  - `bundle.tieredDiscount` (string)

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

  - `bundle.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"

  - `bundle.singleProductSettings` (string)

  - `bundle.subscriptionGroup` (string)

  - `bundle.bundleTopHtml` (string)

  - `bundle.bundleBottomHtml` (string)

  - `bundle.proceedToCheckoutButtonText` (string)

  - `bundle.chooseProductsText` (string)

  - `bundle.name` (string)

  - `bundle.trackInventory` (boolean)

  - `bundle.allowOneTimePurchase` (boolean)

  - `bundle.thirdPartyRule` (boolean)

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

  - `bundle.variants` (string)

  - `bundle.discountedVariants` (string)

  - `bundle.sections` (string)

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

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

  - `bundle.collectionData` (string)

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

  - `bundle.sellingPlanIds` (string)

  - `bundle.minUniqueProductCheck` (boolean)

  - `subscriptionPlanProductInfoMap` (object)

  - `subscriptionPlanVariantMap` (object)

  - `subscriptionGroupPlans` (array)

  - `subscriptionGroupPlans.groupName` (string)

  - `subscriptionGroupPlans.productCount` (integer)

  - `subscriptionGroupPlans.productVariantCount` (integer)

  - `subscriptionGroupPlans.infoJson` (string)

  - `subscriptionGroupPlans.productIds` (string)

  - `subscriptionGroupPlans.variantIds` (string)

  - `subscriptionGroupPlans.variantProductIds` (string)

  - `subscriptionGroupPlans.translations` (string)

  - `subscription` (object)

  - `products` (array)

  - `products.productId` (integer)

  - `products.productTitle` (string)

  - `products.productHandle` (string)


## Response 401 fields

## Response 404 fields

## Response 500 fields