Create a new Build-A-Box subscription bundle

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.

Full behavior, validation rules, and side effects

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)

POST /api/external/v2/build-a-box

Create a new Build-A-Box subscription bundle

cURL

curl --request POST \
  --url https://subscription-admin.appstle.com/api/external/v2/build-a-box \
  --header 'Content-Type: application/json' \
  --data '
{
  "shop": "<string>"
}
'

201

Success Response

{
  "id": 45678,
  "shop": "example-shop.myshopify.com",
  "bundleName": "Premium Coffee Selection",
  "bundleHandle": "premium-coffee-selection",
  "uniqueRef": "bab_abc123xyz",
  "description": "Choose your favorite coffee blends for monthly delivery",
  "buildABoxType": "SINGLE_PRODUCT",
  "buildBoxVersion": "V2",
  "minProductCount": 2,
  "maxProductCount": 5,
  "pricingType": "PER_PRODUCT",
  "discount": 10,
  "discountType": "PERCENTAGE",
  "allowOneTimePurchase": true,
  "active": true,
  "availableProducts": [
    {
      "productId": 111111,
      "variantId": 222222,
      "title": "Medium Roast Coffee - 12oz",
      "price": "14.99",
      "imageUrl": "https://cdn.shopify.com/coffee-medium.jpg"
    },
    {
      "productId": 111111,
      "variantId": 333333,
      "title": "Dark Roast Coffee - 12oz",
      "price": "15.99",
      "imageUrl": "https://cdn.shopify.com/coffee-dark.jpg"
    }
  ],
  "frequencies": [
    {
      "interval": "MONTH",
      "intervalCount": 1,
      "displayName": "Monthly"
    },
    {
      "interval": "WEEK",
      "intervalCount": 2,
      "displayName": "Bi-Weekly"
    }
  ],
  "createdAt": "2024-03-15T10:30:00Z",
  "updatedAt": "2024-03-15T10:30:00Z"
}

Headers

X-API-Key · string

Query Parameters

api_key · string

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

Body

application/json

shop · string · required

id · integer<int64>

subscriptionBundlingEnabled · boolean

subscriptionId · integer<int64>

minProductCount · integer<int32>

maxProductCount · integer<int32>

discount · number<double>

uniqueRef · string

groupName · string

subscriptionBundleLink · string

bundleRedirect · enum<string>

Available options: CART, CHECKOUT, CUSTOM, NONE

customRedirectURL · string

minOrderAmount · number<double>

tieredDiscount · string

productViewStyle · enum<string>

Available options: QUICK_ADD, VIEW_DETAILS

buildABoxType · enum<string>

Available options: CLASSIC, SINGLE_PRODUCT, MIX_AND_MATCH, INFINITE, CUSTOMIZE_BUNDLE, CLASSIC_BUILD_A_BOX, SINGLE_PRODUCT_BUILD_A_BOX, VOLUME_DISCOUNT, DISCOUNTED_PRICING, SHIPPING_DISCOUNT, BUY_X_GET_Y, SECTIONED_BUNDLE

singleProductSettings · string

subscriptionGroup · string

bundleTopHtml · string

bundleBottomHtml · string

proceedToCheckoutButtonText · string

chooseProductsText · string

name · string

trackInventory · boolean

allowOneTimePurchase · boolean

thirdPartyRule · boolean

selectionType · enum<string>

Available options: FIXED, FLEXIBLE

variants · string

discountedVariants · string

sections · string

appliesOn · enum<string>

Available options: PRODUCT, COLLECTION, BOTH, ONE_TIME, SUBSCRIPTION

productDiscountType · enum<string>

Available options: SELECTED_PRODUCT, EACH_PRODUCT

collectionData · string

productSelectionType · enum<string>

Available options: PRODUCT, COLLECTION

sellingPlanIds · string

minUniqueProductCheck · boolean

Response

201

application/json

Build-A-Box subscription bundle successfully created

shop · string · required

id · integer<int64>

subscriptionBundlingEnabled · boolean

subscriptionId · integer<int64>

minProductCount · integer<int32>

maxProductCount · integer<int32>

discount · number<double>

uniqueRef · string

groupName · string

subscriptionBundleLink · string

bundleRedirect · enum<string>

Available options: CART, CHECKOUT, CUSTOM, NONE

customRedirectURL · string

minOrderAmount · number<double>

tieredDiscount · string

productViewStyle · enum<string>

Available options: QUICK_ADD, VIEW_DETAILS

buildABoxType · enum<string>

Available options: CLASSIC, SINGLE_PRODUCT, MIX_AND_MATCH, INFINITE, CUSTOMIZE_BUNDLE, CLASSIC_BUILD_A_BOX, SINGLE_PRODUCT_BUILD_A_BOX, VOLUME_DISCOUNT, DISCOUNTED_PRICING, SHIPPING_DISCOUNT, BUY_X_GET_Y, SECTIONED_BUNDLE

singleProductSettings · string

subscriptionGroup · string

bundleTopHtml · string

bundleBottomHtml · string

proceedToCheckoutButtonText · string

chooseProductsText · string

name · string

trackInventory · boolean

allowOneTimePurchase · boolean

thirdPartyRule · boolean

selectionType · enum<string>

Available options: FIXED, FLEXIBLE

variants · string

discountedVariants · string

sections · string

appliesOn · enum<string>

Available options: PRODUCT, COLLECTION, BOTH, ONE_TIME, SUBSCRIPTION

productDiscountType · enum<string>

Available options: SELECTED_PRODUCT, EACH_PRODUCT

collectionData · string

productSelectionType · enum<string>

Available options: PRODUCT, COLLECTION

sellingPlanIds · string

minUniqueProductCheck · boolean