> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # 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) ## OpenAPI ````yaml /subscription/admin-api-swagger.json get /api/external/v2/build-a-box/{handle} openapi: 3.0.1 info: description: >- Comprehensive API documentation for managing subscriptions, payments, and related operations. These APIs allow you to programmatically manage subscription lifecycles, handle payments, configure products, and integrate subscription functionality into your applications. title: Admin APIs version: 0.0.1 servers: - url: https://subscription-admin.appstle.com security: [] tags: - description: >- Core APIs for managing the complete subscription lifecycle including creation, updates, pausing, resuming, and cancellation of subscriptions. name: Subscription Management - description: >- APIs for managing subscription payment methods, processing payments, handling payment retries, and updating billing information. name: Subscription Payments - description: >- APIs for managing subscription contracts including delivery schedules, pricing, order notes, billing cycles, and shipping addresses. name: Subscription Contracts - description: >- APIs for managing products within subscriptions including adding, removing, updating quantities, and swapping products. name: Subscription Products - description: >- APIs for handling billing operations, payment processing, and financial transactions related to subscriptions. name: Billing & Payments - description: >- APIs for managing discounts and promotional codes applied to subscriptions. name: Subscription Discounts - description: >- APIs for managing one-time add-on products that can be purchased alongside recurring subscription items. name: Subscription One-Time Products - description: >- APIs for managing subscription plans, pricing tiers, and plan configurations. name: Subscription Plans - description: >- APIs for managing customizable product boxes and bundles where customers can select multiple items. name: Build-a-Box & Bundles - description: >- APIs for managing the product catalog including product information, variants, and inventory. name: Product Catalog - description: >- APIs for managing operational settings, configurations, and administrative functions. name: Operations & Settings - description: >- APIs powering the customer-facing portal where subscribers can manage their own subscriptions. name: Customer Portal - description: APIs for managing customer information, profiles, and account details. name: Customers - description: >- APIs for retrieving aggregated subscription data, customer subscription history, and account-level subscription information. name: Subscription Data - description: >- APIs for managing delivery profiles, shipping rates, free shipping configuration, and delivery method options on subscriptions. name: Delivery & Shipping - description: >- APIs for managing storefront customization including custom CSS, theme settings, label translations, and merchant-defined widget configuration. name: Customization - description: >- APIs for configuring cancellation flows, retention offers, cancellation reason management, and win-back automation. name: Customer Retention paths: /api/external/v2/build-a-box/{handle}: get: tags: - Build-a-Box & Bundles summary: Retrieve Build-A-Box bundle details by handle for customer storefront description: >- 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) operationId: getValidSubscriptionCustomerV2_2 parameters: - description: Bundle Handle in: path name: handle required: true schema: type: string - description: API Key (Deprecated - Use Header X-API-Key instead) in: query name: api_key required: false schema: type: string - in: header name: X-API-Key required: false schema: type: string responses: '200': content: application/json: examples: Complete Bundle and Subscription Response: description: Complete Bundle and Subscription Response value: bundle: active: true allowOneTimePurchase: true buildABoxType: SINGLE_PRODUCT buildBoxVersion: V2 bundleHandle: premium-coffee-selection bundleName: Premium Coffee Selection description: Choose your favorite coffee blends for monthly delivery discount: 10 discountType: PERCENTAGE id: 45678 maxProductCount: 5 minProductCount: 2 products: - imageUrl: https://cdn.shopify.com/coffee-medium.jpg price: '14.99' productId: 111111 title: Medium Roast Coffee - 12oz variantId: 222222 shop: example-shop.myshopify.com uniqueRef: bab_abc123xyz createdAt: '2024-03-15T10:30:00Z' subscription: deliveryPolicy: anchors: [] type: RECURRING frequencies: - displayName: Deliver every month interval: MONTH intervalCount: 1 - displayName: Deliver every 2 weeks interval: WEEK intervalCount: 2 sellingPlanGroupId: gid://shopify/SellingPlanGroup/123456 subscriptionPlanId: 98765 updatedAt: '2024-03-20T14:45:00Z' schema: $ref: '#/components/schemas/SubscriptionBundlingResponseV3' description: Bundle and subscription details successfully retrieved '401': content: application/json: example: detail: Valid X-API-Key header or api_key parameter is required status: 401 title: Authentication required type: https://example.com/errors/unauthorized description: Authentication required - Missing or invalid API key '404': content: application/json: examples: Bundle Not Found: description: No bundle exists with the specified handle value: detail: >- No Build-A-Box bundle found with handle 'premium-coffee-selection' status: 404 title: Bundle not found type: https://example.com/errors/not-found Subscription Not Configured: description: Bundle found but subscription plan is not set up value: detail: >- Bundle exists but has no associated subscription plan configured status: 404 title: Subscription configuration missing type: https://example.com/errors/not-found description: >- Bundle not found, subscription not configured, or bundle not available '500': content: application/json: example: detail: >- An unexpected error occurred while retrieving the Build-A-Box bundle status: 500 title: Internal server error type: https://example.com/errors/internal-server-error description: Internal server error components: schemas: SubscriptionBundlingResponseV3: properties: bundle: $ref: '#/components/schemas/SubscriptionBundling' products: items: $ref: '#/components/schemas/ProductInfo' type: array subscription: $ref: '#/components/schemas/SubscriptionGroupPlan' subscriptionGroupPlans: items: $ref: '#/components/schemas/SubscriptionGroupPlan' type: array subscriptionPlanProductInfoMap: additionalProperties: items: $ref: '#/components/schemas/ProductInfo' type: array type: object subscriptionPlanVariantMap: additionalProperties: items: type: string type: array type: object variants: items: type: string type: array type: object SubscriptionBundling: properties: allowOneTimePurchase: type: boolean appliesOn: enum: - PRODUCT - COLLECTION - BOTH - ONE_TIME - SUBSCRIPTION type: string buildABoxType: 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 type: string bundleBottomHtml: type: string bundleRedirect: enum: - CART - CHECKOUT - CUSTOM - NONE type: string bundleTopHtml: type: string chooseProductsText: type: string collectionData: type: string customRedirectURL: type: string discount: format: double type: number discountedVariants: type: string id: format: int64 type: integer maxProductCount: format: int32 type: integer minOrderAmount: format: double type: number minProductCount: format: int32 type: integer minUniqueProductCheck: type: boolean name: type: string proceedToCheckoutButtonText: type: string productDiscountType: enum: - SELECTED_PRODUCT - EACH_PRODUCT type: string productSelectionType: enum: - PRODUCT - COLLECTION type: string productViewStyle: enum: - QUICK_ADD - VIEW_DETAILS type: string sections: type: string selectionType: enum: - FIXED - FLEXIBLE type: string sellingPlanIds: type: string shop: type: string singleProductSettings: type: string subscriptionBundlingEnabled: type: boolean subscriptionGroup: type: string subscriptionId: format: int64 type: integer thirdPartyRule: type: boolean tieredDiscount: type: string trackInventory: type: boolean uniqueRef: type: string variants: type: string required: - shop type: object ProductInfo: properties: id: format: int64 type: integer productHandle: type: string productId: format: int64 type: integer productTitle: type: string shop: type: string required: - shop type: object SubscriptionGroupPlan: properties: groupName: type: string id: format: int64 type: integer infoJson: type: string productCount: format: int32 type: integer productIds: type: string productVariantCount: format: int32 type: integer shop: type: string subscriptionId: format: int64 type: integer translations: type: string variantIds: type: string variantProductIds: type: string required: - shop type: object ````