> ## 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. # 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) ## OpenAPI ````yaml /subscription/admin-api-swagger.json post /api/external/v2/build-a-box 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: post: tags: - Build-a-Box & Bundles summary: Create a new Build-A-Box subscription bundle description: >- 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) operationId: createSubscriptionBundling parameters: - 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 requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriptionBundlingDTO' required: true responses: '201': content: application/json: examples: Success Response: description: Success Response value: active: true allowOneTimePurchase: true availableProducts: - imageUrl: https://cdn.shopify.com/coffee-medium.jpg price: '14.99' productId: 111111 title: Medium Roast Coffee - 12oz variantId: 222222 - imageUrl: https://cdn.shopify.com/coffee-dark.jpg price: '15.99' productId: 111111 title: Dark Roast Coffee - 12oz variantId: 333333 buildABoxType: SINGLE_PRODUCT buildBoxVersion: V2 bundleHandle: premium-coffee-selection bundleName: Premium Coffee Selection createdAt: '2024-03-15T10:30:00Z' description: Choose your favorite coffee blends for monthly delivery discount: 10 discountType: PERCENTAGE frequencies: - displayName: Monthly interval: MONTH intervalCount: 1 - displayName: Bi-Weekly interval: WEEK intervalCount: 2 id: 45678 maxProductCount: 5 minProductCount: 2 pricingType: PER_PRODUCT shop: example-shop.myshopify.com uniqueRef: bab_abc123xyz updatedAt: '2024-03-15T10:30:00Z' schema: $ref: '#/components/schemas/SubscriptionBundlingDTO' description: Build-A-Box subscription bundle successfully created '400': content: application/json: examples: Bundle Already Has ID: description: Bundle Already Has ID value: detail: A new Build-A-Box cannot already have an ID entityName: subscriptionBundling errorKey: idexists status: 400 title: Invalid bundle creation type: https://example.com/errors/bad-request Invalid Limits: description: Invalid Limits value: detail: Minimum product count cannot exceed maximum product count status: 400 title: Invalid product limits type: https://example.com/errors/bad-request Invalid Product Configuration: description: Invalid Product Configuration value: detail: >- One or more products in the bundle are not available or do not exist status: 400 title: Invalid product configuration type: https://example.com/errors/bad-request description: Invalid bundle configuration or validation failure '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 '403': content: application/json: example: detail: API key does not have permission to create Build-A-Box bundles status: 403 title: Insufficient permissions type: https://example.com/errors/forbidden description: Insufficient permissions to create Build-A-Box bundles '422': content: application/json: example: detail: >- Bundle handle must be unique. A bundle with this handle already exists. status: 422 title: Validation failure type: https://example.com/errors/unprocessable-entity description: Unprocessable entity - Business logic validation failure '500': content: application/json: example: detail: >- An unexpected error occurred while creating 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: SubscriptionBundlingDTO: 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 groupName: 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 subscriptionBundleLink: 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 ````