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.

Full behavior, validation rules, and side effects

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)

GET /api/external/v2/build-a-box/{handle}

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

cURL

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/build-a-box/{handle}

200

Complete Bundle and Subscription Response

{
  "bundle": {
    "id": 45678,
    "shop": "example-shop.myshopify.com",
    "bundleName": "Premium Coffee Selection",
    "bundleHandle": "premium-coffee-selection",
    "uniqueRef": "bab_abc123xyz",
    "description": "Choose your favorite coffee blends for monthly delivery",
    "buildABoxType": "SINGLE_PRODUCT",
    "buildBoxVersion": "V2",
    "minProductCount": 2,
    "maxProductCount": 5,
    "discount": 10,
    "discountType": "PERCENTAGE",
    "allowOneTimePurchase": true,
    "active": true,
    "products": [
      {
        "productId": 111111,
        "variantId": 222222,
        "title": "Medium Roast Coffee - 12oz",
        "price": "14.99",
        "imageUrl": "https://cdn.shopify.com/coffee-medium.jpg"
      }
    ]
  },
  "subscription": {
    "subscriptionPlanId": 98765,
    "sellingPlanGroupId": "gid://shopify/SellingPlanGroup/123456",
    "frequencies": [
      {
        "interval": "MONTH",
        "intervalCount": 1,
        "displayName": "Deliver every month"
      },
      {
        "interval": "WEEK",
        "intervalCount": 2,
        "displayName": "Deliver every 2 weeks"
      }
    ],
    "deliveryPolicy": {
      "type": "RECURRING",
      "anchors": []
    }
  },
  "createdAt": "2024-03-15T10:30:00Z",
  "updatedAt": "2024-03-20T14:45:00Z"
}

Headers

X-API-Key · string

Path Parameters

handle · string · required

Bundle Handle

Query Parameters

api_key · string

API Key (Deprecated - Use Header X-API-Key instead)

Response

200

application/json

Bundle and subscription details successfully retrieved

bundle · object

Show child attributes

subscriptionPlanProductInfoMap · object

Show child attributes

subscriptionPlanVariantMap · object

Show child attributes

subscriptionGroupPlans · object[]

Show child attributes

subscription · object

Show child attributes

products · object[]

Show child attributes

variants · string[]