Retrieve a Build-A-Box bundle by ID

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.

Full behavior, validation rules, and side effects

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)

GET /api/external/v2/build-a-box/{id}

Retrieve a Build-A-Box bundle by ID

cURL

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

200

{
  "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,
  "minOrderAmount": 25,
  "pricingType": "PER_PRODUCT",
  "discount": 10,
  "discountType": "PERCENTAGE",
  "allowOneTimePurchase": true,
  "thirdPartyRule": false,
  "trackInventory": true,
  "active": true,
  "productViewStyle": "GRID",
  "proceedToCheckoutButtonText": "Complete Your Subscription",
  "chooseProductsText": "Build Your Perfect Coffee Box",
  "availableProducts": [
    {
      "productId": 111111,
      "variantId": 222222,
      "title": "Medium Roast Coffee - 12oz",
      "price": "14.99",
      "imageUrl": "https://cdn.shopify.com/coffee-medium.jpg",
      "available": true
    },
    {
      "productId": 111111,
      "variantId": 333333,
      "title": "Dark Roast Coffee - 12oz",
      "price": "15.99",
      "imageUrl": "https://cdn.shopify.com/coffee-dark.jpg",
      "available": true
    }
  ],
  "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

Path Parameters

id · integer<int64> · required

Query Parameters

api_key · string

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

Response

200

application/json

Build-A-Box bundle successfully retrieved

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