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.
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
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"allowModifications": true,
"categoryLimits": {
"coffee-dark-roast": {
"max": 3,
"min": 0
},
"coffee-decaf": {
"max": 2,
"min": 0
},
"coffee-flavored": {
"max": 2,
"min": 0
},
"coffee-light-roast": {
"max": 3,
"min": 0
},
"coffee-medium-roast": {
"max": 3,
"min": 0
}
},
"createdAt": "2024-01-15T10:30:00Z",
"discounts": {
"enableVolumeDiscounts": true,
"volumeDiscountTiers": [
{
"discountPercent": 10,
"minProducts": 5
},
{
"discountPercent": 15,
"minProducts": 7
}
]
},
"displaySettings": {
"enableFiltering": true,
"enableSearch": true,
"layoutType": "GRID",
"productsPerRow": 3,
"showBundlePreview": true,
"showPricing": false,
"showProductDescriptions": true,
"showProductImages": true
},
"enableProductRotation": true,
"enabled": true,
"fixedBundlePrice": 59.99,
"id": 12345,
"lockAfterFirstOrder": false,
"maxBundleValue": 100,
"maxProducts": 8,
"maxSwapsPerCycle": 2,
"minBundleValue": 40,
"minProducts": 3,
"modificationCutoffDays": 5,
"notifications": {
"reminderDaysBeforeOrder": 7,
"sendBundleCreatedEmail": true,
"sendBundleModifiedConfirmation": true,
"sendModificationReminderEmail": true
},
"pricingModel": "FIXED_PRICE",
"recommendations": {
"enableRecommendations": true,
"recommendationStrategy": "POPULAR_AND_PERSONALIZED",
"showBestSellers": true,
"showCuratedBundles": true
},
"requireCategoryDiversity": true,
"shop": "example-shop.myshopify.com",
"substitution": {
"allowCustomerToApproveSubstitutions": false,
"allowSubstitutions": true,
"notifyCustomerOfSubstitutions": true,
"substitutionMethod": "SIMILAR_PRODUCT"
},
"updatedAt": "2024-02-20T14:45:00Z"
}{
"detail": "Valid X-API-Key header is required",
"status": 401,
"title": "Authentication required",
"type": "https://example.com/errors/unauthorized"
}{
"detail": "API key does not have permission to view bundle settings",
"status": 403,
"title": "Insufficient permissions",
"type": "https://example.com/errors/forbidden"
}{
"detail": "Subscription bundle settings have not been configured for this shop",
"status": 404,
"title": "Settings not found",
"type": "https://example.com/errors/not-found"
}Headers
Path Parameters
Query Parameters
API Key (Deprecated - Use Header X-API-Key instead)
Response
Bundle settings successfully retrieved
CART, CHECKOUT, CUSTOM DEFAULT, MAX_QUANTITY, STOP_AUTO_OPEN, MIN_AMOUNT Show child attributes
Show child attributes
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}';
const options = {method: 'GET'};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://subscription-admin.appstle.com/api/external/v2/subscription-bundle-settings/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"allowModifications": true,
"categoryLimits": {
"coffee-dark-roast": {
"max": 3,
"min": 0
},
"coffee-decaf": {
"max": 2,
"min": 0
},
"coffee-flavored": {
"max": 2,
"min": 0
},
"coffee-light-roast": {
"max": 3,
"min": 0
},
"coffee-medium-roast": {
"max": 3,
"min": 0
}
},
"createdAt": "2024-01-15T10:30:00Z",
"discounts": {
"enableVolumeDiscounts": true,
"volumeDiscountTiers": [
{
"discountPercent": 10,
"minProducts": 5
},
{
"discountPercent": 15,
"minProducts": 7
}
]
},
"displaySettings": {
"enableFiltering": true,
"enableSearch": true,
"layoutType": "GRID",
"productsPerRow": 3,
"showBundlePreview": true,
"showPricing": false,
"showProductDescriptions": true,
"showProductImages": true
},
"enableProductRotation": true,
"enabled": true,
"fixedBundlePrice": 59.99,
"id": 12345,
"lockAfterFirstOrder": false,
"maxBundleValue": 100,
"maxProducts": 8,
"maxSwapsPerCycle": 2,
"minBundleValue": 40,
"minProducts": 3,
"modificationCutoffDays": 5,
"notifications": {
"reminderDaysBeforeOrder": 7,
"sendBundleCreatedEmail": true,
"sendBundleModifiedConfirmation": true,
"sendModificationReminderEmail": true
},
"pricingModel": "FIXED_PRICE",
"recommendations": {
"enableRecommendations": true,
"recommendationStrategy": "POPULAR_AND_PERSONALIZED",
"showBestSellers": true,
"showCuratedBundles": true
},
"requireCategoryDiversity": true,
"shop": "example-shop.myshopify.com",
"substitution": {
"allowCustomerToApproveSubstitutions": false,
"allowSubstitutions": true,
"notifyCustomerOfSubstitutions": true,
"substitutionMethod": "SIMILAR_PRODUCT"
},
"updatedAt": "2024-02-20T14:45:00Z"
}{
"detail": "Valid X-API-Key header is required",
"status": 401,
"title": "Authentication required",
"type": "https://example.com/errors/unauthorized"
}{
"detail": "API key does not have permission to view bundle settings",
"status": 403,
"title": "Insufficient permissions",
"type": "https://example.com/errors/forbidden"
}{
"detail": "Subscription bundle settings have not been configured for this shop",
"status": 404,
"title": "Settings not found",
"type": "https://example.com/errors/not-found"
}