# Build-a-Box & Bundles

APIs for managing customizable product boxes and bundles where customers can select multiple items.

## Generate discount code for bundle

 - [PUT /api/external/v2/subscription-bundlings/discount/{token}](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/generatediscountv2.md): Generates a discount code for a subscription bundle. This endpoint creates a Shopify discount code that can be applied to bundle subscriptions, typically used during the checkout process.

Discount Code Generation:
- Creates a unique discount code in Shopify
- Associates the discount with the bundle
- Configures discount rules and limitations
- Sets expiration dates if specified
- Applies usage limits if configured

Discount Configuration Options:
- Discount type (percentage, fixed amount, or free shipping)
- Discount value/amount
- Minimum purchase requirements
- Maximum usage count
- Expiration date
- Customer eligibility rules

Use Cases:
- Promotional campaigns for bundles
- Welcome discounts for new subscribers
- Loyalty rewards for existing customers
- Special offers and limited-time promotions
- Partner/affiliate discount codes

Important Notes:
- Discount codes are created in Shopify and follow Shopify's discount rules
- Codes can be single-use or multi-use depending on configuration
- Expired or depleted codes cannot be reused

Authentication: Requires valid X-API-Key header

## Update subscription bundling configuration

 - [PUT /api/external/v2/subscription-bundling/update](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/getupdatesubscriptionbundling.md): Updates the configuration for one or more subscription bundles (Build-a-Box). This endpoint allows bulk updates to bundle product selections, quantities, and configurations.

Subscription Bundling/Build-a-Box:
Subscription bundling allows customers to create custom product bundles that are delivered on a recurring basis. Customers can select multiple products to be included in each delivery, creating a personalized subscription box.

Update Capabilities:
- Modify product selections within a bundle
- Update product quantities
- Change bundle configuration settings
- Bulk update multiple bundles at once

Use Cases:
- Customer updates their bundle product selections
- Swap products in an existing bundle
- Adjust quantities for products in the bundle
- Programmatically manage bundle configurations

Important Notes:
- Updates are identified by bundle handle (unique identifier)
- Only active bundles can be updated
- Product availability is validated before update

Authentication: Requires valid X-API-Key header

## Update an existing Build-A-Box subscription bundle

 - [PUT /api/external/v2/build-a-box](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/updatesubscriptionbundling.md): 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)

## Create a new Build-A-Box subscription bundle

 - [POST /api/external/v2/build-a-box](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/createsubscriptionbundling.md): 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)

## Get bundle details by handle

 - [GET /api/external/v2/subscription-bundlings/external/get-bundle/{handle}](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/getvalidsubscriptioncustomerv2_1.md): Retrieves complete details for a subscription bundle using its unique handle. This endpoint returns the bundle configuration, included products, pricing, and available subscription options.

Bundle Information Returned:
- Bundle name and description
- Product selections with quantities
- Pricing and discounts
- Available subscription frequencies
- Bundle status and availability
- Product images and details

Use Cases:
- Display bundle details on product pages
- Show bundle contents in customer portal
- Fetch bundle configuration for cart/checkout
- Integration with external systems
- Build custom bundle selection interfaces

Bundle Handle:
The handle is a unique, URL-friendly identifier for the bundle. It's typically generated when the bundle is created and remains constant throughout the bundle's lifecycle.

Authentication: Requires valid X-API-Key header

## Get subscription bundle settings (Build-a-Box configuration)

 - [GET /api/external/v2/subscription-bundle-settings/{id}](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/getsubscriptionbundlesettingsv2.md): Retrieves the configuration settings for subscription bundles (also known as Build-a-Box or customizable subscription boxes). This endpoint returns all settings that control how customers can create and manage their custom subscription bundles.

What are Subscription Bundles (Build-a-Box)?
Subscription bundles allow customers to create personalized subscription boxes by selecting multiple products from a curated collection. Instead of subscribing to a fixed product, customers build their own custom bundle that gets delivered on a recurring basis. This is perfect for coffee subscriptions, snack boxes, beauty boxes, supplement packs, and any product category where variety and personalization drive customer satisfaction.

Bundle Configuration Settings:

1. Product Selection Rules:
- Minimum number of products required in bundle
- Maximum number of products allowed in bundle
- Product categories available for selection
- Variant selection constraints
- Quantity limits per product
- Total bundle value constraints (min/max price)

2. Bundle Behavior:
- Allow customers to modify bundle between orders
- Lock bundle after first order
- Enable automatic product rotation
- Allow quantity adjustments
- Substitution rules when products unavailable

3. Pricing & Discounts:
- Bundle pricing model (fixed price vs. sum of products)
- Volume discounts based on bundle size
- Tiered pricing structures
- Promotional pricing for bundles
- Discount application rules

4. UI/UX Settings:
- Bundle builder interface layout
- Product display format (grid/list)
- Images and descriptions shown
- Filter and search options
- Preview and summary display
- Mobile responsiveness settings

5. Fulfillment Options:
- Bundling method (ship together vs. separate)
- Packaging preferences
- Custom box selection
- Gift message options
- Delivery instructions

6. Customer Experience:
- Welcome flow for new bundle subscribers
- Modification window before each order
- Reminder notifications to update bundle
- Recommendation engine settings
- Save favorite bundle configurations

Common Bundle Types:

Coffee Subscription Bundle:
- Select 3-5 coffee varieties per month
- Choose roast levels, origins, or flavors
- Option to rotate selections monthly
- Fixed price regardless of selection

Snack Box Bundle:
- Choose 10 items from 50+ snacks
- Category limits (e.g., max 3 sweet, 7 savory)
- Dietary restriction filters (vegan, gluten-free)
- Tiered pricing based on bundle size

Beauty Box Bundle:
- Select products from skincare, makeup, haircare categories
- Minimum 5 products, maximum 8 products
- Total value must be between $40-$100
- Can swap 2 products each month

Vitamin/Supplement Bundle:
- Build personalized supplement pack
- Health goal-based recommendations
- Compatibility checking (ingredient interactions)
- Fixed monthly price for up to 5 supplements

Use Cases:
- Configure bundle builder in customer portal
- Validate customer bundle selections against rules
- Display bundle configuration options during signup
- Integrate with checkout to show bundle pricing
- Build custom bundle management interfaces
- Sync bundle settings with mobile apps
- Generate bundle recommendation algorithms

Important Notes:
- Settings apply to all subscription bundles in the shop
- Changes affect new bundles immediately
- Existing bundles maintain their original configuration unless migrated
- Product availability is checked in real-time during bundle creation
- Bundle modifications may have cutoff times before order processing

Best Practices:
- Set reasonable min/max limits to balance choice and complexity
- Provide clear guidance on bundle building process
- Use category limits to ensure variety
- Enable modification windows to boost engagement
- Offer curated bundle templates as starting points
- Implement substitution logic for out-of-stock items
- Test bundle builder UX across devices

Authentication: Requires valid X-API-Key header

## Retrieve a Build-A-Box bundle by ID

 - [GET /api/external/v2/build-a-box/{id}](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/getsubscriptionbundling.md): Fetches the complete configuration and details of a specific Build-A-Box subscription bundle using its unique identifier. This endpoint returns all bundle settings including products, pricing, rules, and delivery options.

What You'll Receive:
- Complete Bundle Configuration: All settings and properties
- Product Information: Full list of available products with details
- Pricing Structure: Discount rules, pricing type, and promotional settings
- Delivery Options: Subscription frequencies and delivery intervals
- Business Rules: Product limits, combination rules, and restrictions
- Status Information: Active/inactive state and timestamps
- Customization Settings: Allow one-time purchases, product swaps, etc.

Use Cases:
1. Bundle Management: Retrieve current bundle settings for review or editing
2. Integration Sync: Synchronize bundle data with external systems
3. Customer Portal: Display bundle options and configurations
4. Audit & Reporting: Track bundle configurations over time
5. Validation: Verify bundle setup before making changes
6. Cloning: Retrieve settings to duplicate a successful bundle
7. Troubleshooting: Debug subscription issues by reviewing bundle config

Response Details:
The response includes comprehensive information about the bundle:
- Bundle Metadata: ID, shop, name, handle, unique reference
- Product Pool: All products available for customer selection
- Selection Rules: Min/max product counts, quantity limits
- Pricing Configuration: Discount percentages, pricing models
- Subscription Options: Available delivery frequencies
- Display Settings: Product view styles, custom HTML, button text
- Advanced Features: Third-party rules, inventory tracking, selection types
- Timestamps: Creation and last update dates

Authorization:
- You can only retrieve bundles that belong to your authenticated shop
- The system verifies shop ownership before returning bundle data
- Returns 404 if bundle doesn't exist or doesn't belong to your shop

Integration Tips:
- Cache bundle data to reduce API calls for frequently accessed bundles
- Use this endpoint to verify bundle existence before creating subscriptions
- Combine with update endpoint for edit workflows (get → modify → update)
- Check the active field to determine if the bundle is available to customers
- Review availableProducts array to ensure product inventory availability

Performance Considerations:
- Response size varies based on number of products in the bundle
- Bundles with extensive custom HTML or large product pools return more data
- Consider requesting only necessary fields if partial data is sufficient
- Use batch operations if retrieving multiple bundles

Authentication: Requires valid X-API-Key header or api_key parameter (deprecated)

## Delete a Build-A-Box subscription bundle

 - [DELETE /api/external/v2/build-a-box/{id}](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/deletesubscriptionbundling.md): 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)

## Retrieve Build-A-Box bundle details by handle for customer storefront

 - [GET /api/external/v2/build-a-box/{handle}](https://developers.subscription.appstle.com/external-api-swagger/build-a-box-and-bundles/getvalidsubscriptioncustomerv2_2.md): 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)