Update an existing Build-A-Box subscription bundle

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.

Full behavior, validation rules, and side effects

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)

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

Update an existing Build-A-Box subscription bundle

cURL

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

200

Updated Bundle

{
  "id": 45678,
  "shop": "example-shop.myshopify.com",
  "bundleName": "Premium Coffee Selection - Updated",
  "bundleHandle": "premium-coffee-selection",
  "uniqueRef": "bab_abc123xyz",
  "description": "Choose from our expanded selection of artisan coffee blends",
  "buildABoxType": "SINGLE_PRODUCT",
  "buildBoxVersion": "V2",
  "minProductCount": 3,
  "maxProductCount": 6,
  "pricingType": "PER_PRODUCT",
  "discount": 15,
  "discountType": "PERCENTAGE",
  "allowOneTimePurchase": true,
  "active": true,
  "availableProducts": [
    {
      "productId": 111111,
      "variantId": 222222,
      "title": "Medium Roast Coffee - 12oz",
      "price": "14.99"
    },
    {
      "productId": 111111,
      "variantId": 333333,
      "title": "Dark Roast Coffee - 12oz",
      "price": "15.99"
    },
    {
      "productId": 111111,
      "variantId": 444444,
      "title": "Espresso Roast Coffee - 12oz",
      "price": "16.99"
    }
  ],
  "frequencies": [
    {
      "interval": "MONTH",
      "intervalCount": 1,
      "displayName": "Monthly"
    },
    {
      "interval": "WEEK",
      "intervalCount": 2,
      "displayName": "Bi-Weekly"
    }
  ],
  "createdAt": "2024-03-15T10:30:00Z",
  "updatedAt": "2024-03-20T14:45: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

200

application/json

Build-A-Box subscription bundle successfully updated

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