> ## 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. # Update an existing Build-A-Box subscription bundle > Updates an existing Build-A-Box subscription bundle with new configuration settings, product selections, pricing rules, or other bundle attributes. This endpoint allows you to modify any aspect of a previously created bundle while maintaining its unique identifier and shop association. **What Can Be Updated:** - **Bundle Information**: Name, description, handle, and display settings - **Product Configuration**: Available products, product pool, and selection rules - **Quantity Limits**: Minimum and maximum product counts per box - **Pricing Settings**: Pricing type, discount rules, and promotional offers - **Delivery Options**: Subscription frequencies and delivery intervals - **Business Rules**: Product combination rules, category restrictions - **Status**: Active/inactive state for customer visibility - **Customization Options**: Allow product swaps, one-time purchases **Update Behavior:** - The bundle ID must be provided in the request body - Shop ownership is verified - you can only update bundles belonging to your shop - All fields in the request body will update the corresponding bundle properties - Partial updates are supported - only include fields you want to change - The update is atomic - either all changes succeed or none are applied - Existing subscriptions using this bundle are not automatically affected **Impact on Active Subscriptions:** - Changes to product availability affect future customer selections - Pricing updates apply to new subscriptions but not existing ones by default - Quantity limit changes are enforced on next customer modification - Frequency changes only affect new subscriptions - Deactivating a bundle prevents new subscriptions but maintains existing ones **Common Update Scenarios:** 1. **Add/Remove Products**: Update the available product pool 2. **Adjust Pricing**: Change discount percentages or pricing models 3. **Modify Limits**: Update minimum/maximum product selection rules 4. **Change Frequencies**: Add or remove subscription interval options 5. **Update Content**: Modify bundle name, description, or images 6. **Toggle Status**: Activate or deactivate bundle availability 7. **Refine Rules**: Adjust product combination or category restrictions **Best Practices:** - Verify product availability before adding to the bundle - Test pricing changes with sample calculations - Communicate bundle changes to existing subscribers - Use inactive status for testing changes before making them live - Keep bundle handles consistent for external integrations - Document major changes for customer support reference - Consider seasonal or promotional updates to keep offerings fresh **Validation Rules:** - Bundle ID is required and must exist - Shop must match the authenticated shop (cannot transfer bundles) - All referenced products must be valid and available - Minimum product count cannot exceed maximum product count - Pricing values must be non-negative - Bundle handle should remain unique across all bundles **Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated) ## OpenAPI ````yaml /subscription/admin-api-swagger.json put /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: put: tags: - Build-a-Box & Bundles summary: Update an existing Build-A-Box subscription bundle description: >- Updates an existing Build-A-Box subscription bundle with new configuration settings, product selections, pricing rules, or other bundle attributes. This endpoint allows you to modify any aspect of a previously created bundle while maintaining its unique identifier and shop association. **What Can Be Updated:** - **Bundle Information**: Name, description, handle, and display settings - **Product Configuration**: Available products, product pool, and selection rules - **Quantity Limits**: Minimum and maximum product counts per box - **Pricing Settings**: Pricing type, discount rules, and promotional offers - **Delivery Options**: Subscription frequencies and delivery intervals - **Business Rules**: Product combination rules, category restrictions - **Status**: Active/inactive state for customer visibility - **Customization Options**: Allow product swaps, one-time purchases **Update Behavior:** - The bundle ID must be provided in the request body - Shop ownership is verified - you can only update bundles belonging to your shop - All fields in the request body will update the corresponding bundle properties - Partial updates are supported - only include fields you want to change - The update is atomic - either all changes succeed or none are applied - Existing subscriptions using this bundle are not automatically affected **Impact on Active Subscriptions:** - Changes to product availability affect future customer selections - Pricing updates apply to new subscriptions but not existing ones by default - Quantity limit changes are enforced on next customer modification - Frequency changes only affect new subscriptions - Deactivating a bundle prevents new subscriptions but maintains existing ones **Common Update Scenarios:** 1. **Add/Remove Products**: Update the available product pool 2. **Adjust Pricing**: Change discount percentages or pricing models 3. **Modify Limits**: Update minimum/maximum product selection rules 4. **Change Frequencies**: Add or remove subscription interval options 5. **Update Content**: Modify bundle name, description, or images 6. **Toggle Status**: Activate or deactivate bundle availability 7. **Refine Rules**: Adjust product combination or category restrictions **Best Practices:** - Verify product availability before adding to the bundle - Test pricing changes with sample calculations - Communicate bundle changes to existing subscribers - Use inactive status for testing changes before making them live - Keep bundle handles consistent for external integrations - Document major changes for customer support reference - Consider seasonal or promotional updates to keep offerings fresh **Validation Rules:** - Bundle ID is required and must exist - Shop must match the authenticated shop (cannot transfer bundles) - All referenced products must be valid and available - Minimum product count cannot exceed maximum product count - Pricing values must be non-negative - Bundle handle should remain unique across all bundles **Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated) operationId: updateSubscriptionBundling 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: '200': content: application/json: examples: Updated Bundle: description: Updated Bundle value: active: true allowOneTimePurchase: true availableProducts: - price: '14.99' productId: 111111 title: Medium Roast Coffee - 12oz variantId: 222222 - price: '15.99' productId: 111111 title: Dark Roast Coffee - 12oz variantId: 333333 - price: '16.99' productId: 111111 title: Espresso Roast Coffee - 12oz variantId: 444444 buildABoxType: SINGLE_PRODUCT buildBoxVersion: V2 bundleHandle: premium-coffee-selection bundleName: Premium Coffee Selection - Updated createdAt: '2024-03-15T10:30:00Z' description: >- Choose from our expanded selection of artisan coffee blends discount: 15 discountType: PERCENTAGE frequencies: - displayName: Monthly interval: MONTH intervalCount: 1 - displayName: Bi-Weekly interval: WEEK intervalCount: 2 id: 45678 maxProductCount: 6 minProductCount: 3 pricingType: PER_PRODUCT shop: example-shop.myshopify.com uniqueRef: bab_abc123xyz updatedAt: '2024-03-20T14:45:00Z' schema: $ref: '#/components/schemas/SubscriptionBundlingDTO' description: Build-A-Box subscription bundle successfully updated '400': content: application/json: examples: Invalid Configuration: description: Invalid Configuration value: detail: >- Minimum product count (5) cannot exceed maximum product count (3) status: 400 title: Invalid configuration type: https://example.com/errors/bad-request Missing Bundle ID: description: Missing Bundle ID value: detail: Bundle ID is required for updates entityName: subscriptionBundling errorKey: idnull status: 400 title: Invalid bundle update type: https://example.com/errors/bad-request Unauthorized Access: description: Unauthorized Access value: detail: >- Unauthorized access or resource not found. Bundle does not belong to your shop. entityName: subscriptionBundling errorKey: unauthorized status: 400 title: Unauthorized access type: https://example.com/errors/bad-request description: Invalid update request 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 '404': content: application/json: example: detail: No Build-A-Box bundle found with ID 45678 status: 404 title: Bundle not found type: https://example.com/errors/not-found description: Bundle not found with the specified ID '500': content: application/json: example: detail: >- An unexpected error occurred while updating 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 ````