> ## 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. # Delete a Build-A-Box subscription bundle > Permanently removes a Build-A-Box subscription bundle from your shop. This operation is irreversible and will prevent new customers from subscribing to this bundle. However, existing subscriptions using this bundle will remain active. **Important Deletion Rules:** 1. **Active Subscriptions Check**: The system prevents deletion if there are active subscriptions using this bundle 2. **Alternative Approach**: If active subscriptions exist, you must first deactivate the bundle instead of deleting it 3. **Shop Ownership**: You can only delete bundles that belong to your authenticated shop 4. **Irreversible**: Once deleted, the bundle configuration cannot be recovered 5. **Clean Deletion**: Only bundles with zero associated subscriptions can be permanently removed **Deletion Workflow:** ``` 1. Request deletion of bundle with ID 2. System checks for shop ownership 3. System counts active subscriptions using this bundle 4. If subscriptions exist → Returns error with subscription count 5. If no subscriptions → Deletes bundle permanently 6. Returns success (204 No Content) ``` **When Deletion is Blocked:** The system will prevent deletion and return a 400 error if: - One or more active subscriptions are using this bundle - The error message will include the exact count of active subscriptions - Example: "Deleting Build-A-Box is not possible, 47 subscriptions found. You may deactivate the Build-A-Box." **Recommended Workflow for Active Bundles:** If you want to stop offering a bundle that has active subscribers: 1. **Update** the bundle to set `active: false` (this prevents new subscriptions) 2. **Monitor** existing subscriptions until they naturally expire or are cancelled 3. **Migrate** customers to a different bundle if needed 4. **Delete** the bundle once all subscriptions have been resolved **Use Cases:** - **Testing Cleanup**: Remove test bundles created during development - **Failed Configurations**: Delete bundles that were incorrectly set up - **Seasonal Offerings**: Remove time-limited bundles after the season ends (if no subscriptions) - **Product Discontinuation**: Clean up bundles for discontinued product lines - **Duplicate Bundles**: Remove accidentally created duplicate configurations **Best Practices:** - **Check Before Deleting**: Always verify no active subscriptions exist - **Use Deactivation First**: Set bundles to inactive before attempting deletion - **Document Changes**: Keep records of when and why bundles were deleted - **Backup Configuration**: Save bundle settings before deletion for potential recreation - **Communicate Changes**: Inform team members about bundle removals - **Consider Archiving**: For historical reference, deactivate rather than delete when possible **What Happens After Deletion:** - Bundle configuration is permanently removed from the database - Bundle ID becomes available for reuse (though not recommended) - Bundle handle becomes available for new bundles - External integrations referencing this bundle will receive 404 errors - Analytics and historical data may reference the deleted bundle ID **Error Prevention:** Before attempting deletion, you can: 1. Query active subscriptions to check for bundle usage 2. Set the bundle to inactive status first 3. Wait for all subscriptions to complete or migrate customers 4. Then proceed with deletion **Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated) ## OpenAPI ````yaml /subscription/admin-api-swagger.json delete /api/external/v2/build-a-box/{id} 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/{id}: delete: tags: - Build-a-Box & Bundles summary: Delete a Build-A-Box subscription bundle description: >- Permanently removes a Build-A-Box subscription bundle from your shop. This operation is irreversible and will prevent new customers from subscribing to this bundle. However, existing subscriptions using this bundle will remain active. **Important Deletion Rules:** 1. **Active Subscriptions Check**: The system prevents deletion if there are active subscriptions using this bundle 2. **Alternative Approach**: If active subscriptions exist, you must first deactivate the bundle instead of deleting it 3. **Shop Ownership**: You can only delete bundles that belong to your authenticated shop 4. **Irreversible**: Once deleted, the bundle configuration cannot be recovered 5. **Clean Deletion**: Only bundles with zero associated subscriptions can be permanently removed **Deletion Workflow:** ``` 1. Request deletion of bundle with ID 2. System checks for shop ownership 3. System counts active subscriptions using this bundle 4. If subscriptions exist → Returns error with subscription count 5. If no subscriptions → Deletes bundle permanently 6. Returns success (204 No Content) ``` **When Deletion is Blocked:** The system will prevent deletion and return a 400 error if: - One or more active subscriptions are using this bundle - The error message will include the exact count of active subscriptions - Example: "Deleting Build-A-Box is not possible, 47 subscriptions found. You may deactivate the Build-A-Box." **Recommended Workflow for Active Bundles:** If you want to stop offering a bundle that has active subscribers: 1. **Update** the bundle to set `active: false` (this prevents new subscriptions) 2. **Monitor** existing subscriptions until they naturally expire or are cancelled 3. **Migrate** customers to a different bundle if needed 4. **Delete** the bundle once all subscriptions have been resolved **Use Cases:** - **Testing Cleanup**: Remove test bundles created during development - **Failed Configurations**: Delete bundles that were incorrectly set up - **Seasonal Offerings**: Remove time-limited bundles after the season ends (if no subscriptions) - **Product Discontinuation**: Clean up bundles for discontinued product lines - **Duplicate Bundles**: Remove accidentally created duplicate configurations **Best Practices:** - **Check Before Deleting**: Always verify no active subscriptions exist - **Use Deactivation First**: Set bundles to inactive before attempting deletion - **Document Changes**: Keep records of when and why bundles were deleted - **Backup Configuration**: Save bundle settings before deletion for potential recreation - **Communicate Changes**: Inform team members about bundle removals - **Consider Archiving**: For historical reference, deactivate rather than delete when possible **What Happens After Deletion:** - Bundle configuration is permanently removed from the database - Bundle ID becomes available for reuse (though not recommended) - Bundle handle becomes available for new bundles - External integrations referencing this bundle will receive 404 errors - Analytics and historical data may reference the deleted bundle ID **Error Prevention:** Before attempting deletion, you can: 1. Query active subscriptions to check for bundle usage 2. Set the bundle to inactive status first 3. Wait for all subscriptions to complete or migrate customers 4. Then proceed with deletion **Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated) operationId: deleteSubscriptionBundling parameters: - in: path name: id required: true schema: format: int64 type: integer - 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: '204': content: application/json: {} description: Build-A-Box bundle successfully deleted. No content returned. '400': content: application/json: examples: Active Subscriptions Exist: description: Bundle has 47 active subscriptions and cannot be deleted value: detail: >- Deleting Build-A-Box is not possible, 47 subscriptions found. You may deactivate the Build-A-Box. entityName: subscriptionBundling errorKey: activeSubscriptionsExist status: 400 title: Cannot delete bundle 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: Deletion blocked due to active subscriptions 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 for your shop status: 404 title: Bundle not found type: https://example.com/errors/not-found description: Bundle not found or does not belong to your shop '500': content: application/json: example: detail: >- An unexpected error occurred while deleting the Build-A-Box bundle status: 500 title: Internal server error type: https://example.com/errors/internal-server-error description: Internal server error ````