External APIs (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Retrieves complete details for a subscription bundle using its unique handle. This endpoint returns the bundle configuration, included products, pricing, and available subscription options.

Bundle Information Returned:

• Bundle name and description
• Product selections with quantities
• Pricing and discounts
• Available subscription frequencies
• Bundle status and availability
• Product images and details

Use Cases:

• Display bundle details on product pages
• Show bundle contents in customer portal
• Fetch bundle configuration for cart/checkout
• Integration with external systems
• Build custom bundle selection interfaces

Bundle Handle: The handle is a unique, URL-friendly identifier for the bundle. It's typically generated when the bundle is created and remains constant throughout the bundle's lifecycle.

Authentication: Requires valid X-API-Key header

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

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.

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)