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 /:

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

{
  "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:

// 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)