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.

Full behavior, validation rules, and side effects

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)

DELETE /api/external/v2/build-a-box/{id}

Delete a Build-A-Box subscription bundle

cURL

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

204

Headers

X-API-Key · string

Path Parameters

id · integer<int64> · required

Query Parameters

api_key · string

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

Response

204

application/json

Build-A-Box bundle successfully deleted. No content returned.