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

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.

Full behavior, validation rules, and side effects

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

GET /api/external/v2/subscription-bundle-settings/{id}

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

cURL

curl --request GET \
  --url https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}

200

{
  "id": 12345,
  "shop": "example-shop.myshopify.com",
  "enabled": true,
  "minProducts": 3,
  "maxProducts": 8,
  "minBundleValue": 40,
  "maxBundleValue": 100,
  "pricingModel": "FIXED_PRICE",
  "fixedBundlePrice": 59.99,
  "allowModifications": true,
  "modificationCutoffDays": 5,
  "lockAfterFirstOrder": false,
  "enableProductRotation": true,
  "maxSwapsPerCycle": 2,
  "requireCategoryDiversity": true,
  "categoryLimits": {
    "coffee-light-roast": {
      "min": 0,
      "max": 3
    },
    "coffee-medium-roast": {
      "min": 0,
      "max": 3
    },
    "coffee-dark-roast": {
      "min": 0,
      "max": 3
    },
    "coffee-decaf": {
      "min": 0,
      "max": 2
    },
    "coffee-flavored": {
      "min": 0,
      "max": 2
    }
  },
  "displaySettings": {
    "layoutType": "GRID",
    "productsPerRow": 3,
    "showProductImages": true,
    "showProductDescriptions": true,
    "showPricing": false,
    "enableFiltering": true,
    "enableSearch": true,
    "showBundlePreview": true
  },
  "notifications": {
    "sendBundleCreatedEmail": true,
    "sendModificationReminderEmail": true,
    "reminderDaysBeforeOrder": 7,
    "sendBundleModifiedConfirmation": true
  },
  "substitution": {
    "allowSubstitutions": true,
    "substitutionMethod": "SIMILAR_PRODUCT",
    "notifyCustomerOfSubstitutions": true,
    "allowCustomerToApproveSubstitutions": false
  },
  "recommendations": {
    "enableRecommendations": true,
    "recommendationStrategy": "POPULAR_AND_PERSONALIZED",
    "showBestSellers": true,
    "showCuratedBundles": true
  },
  "discounts": {
    "enableVolumeDiscounts": true,
    "volumeDiscountTiers": [
      {
        "minProducts": 5,
        "discountPercent": 10
      },
      {
        "minProducts": 7,
        "discountPercent": 15
      }
    ]
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-02-20T14:45:00Z"
}

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

200

application/json

Bundle settings successfully retrieved

shop · string · required

selectedFrequencyLabelText · string · required

addButtonText · string · required

selectMinimumProductButtonText · string · required

productsToProceedText · string · required

proceedToCheckoutButtonText · string · required

myDeliveryText · string · required

id · integer<int64>

bundleTopHtml · string

bundleBottomHtml · string

failedToAddTitleText · string

okBtnText · string

failedToAddMsgText · string

buttonColor · string

backgroundColor · string

pageBackgroundColor · string

buttonBackgroundColor · string

variantNotAvailable · string

bundleRedirect · enum<string>

Available options: CART, CHECKOUT, CUSTOM

isBundleWithoutScroll · boolean

descriptionLength · integer<int32>

currencySwitcherClassName · string

productPriceFormatField · string

customRedirectURL · string

viewProduct · string

productDetails · string

editQuantity · string

cart · string

shoppingCart · string

title · string

tieredDiscount · string

subtotal · string

checkoutMessage · string

continueShopping · string

spendAmountGetDiscount · string

buyQuantityGetDiscount · string

removeItem · string

showCompareAtPrice · boolean

enableRedirectToProductPage · boolean

disableProductDescription · boolean

enableDisplayProductVendor · boolean

enableDisplayProductType · boolean

enableCustomAdvancedFields · boolean

hideProductSearchBox · boolean

productFilterConfig · string

enableProductDetailButton · boolean

enableShowProductBasePrice · boolean

enableClearCartSelectedProducts · boolean

enableSkieyBABHeader · boolean

enableOpeningSidebar · boolean

rightSidebarHTML · string

leftSidebarHTML · string

isMergeIntoSingleBABVariantDropdown · boolean

enableEditQuantityTextbox · boolean

displayUnavailableProduct · boolean

allowAddUnavailableProduct · boolean

showOrderNoteField · boolean

showSubLoyaltyTable · boolean

restrictPriceRateCalculation · boolean

disableProductCardImageSlider · boolean

skipFilterVariantsByAllocationsId · boolean

openingSidebarType · enum<string>

Available options: DEFAULT, MAX_QUANTITY, STOP_AUTO_OPEN, MIN_AMOUNT

moveOneTimePurchaseToTop · boolean

skipFirstPage · boolean

congratsMessageText · string

spentText · string

quantityLabel · string

variantLabelTextV2 · string

itemsText · string

shopCustomizationData · object[]

Show child attributes

productTitleFontColor · string