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 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)

Permanently removes a Build-A-Box subscription bundle from your shop. This operation is irreversible and will prevent new customers from subscribing to this bundle. However, existing subscriptions using this bundle will remain active.

Important Deletion Rules:

1. Active Subscriptions Check: The system prevents deletion if there are active subscriptions using this bundle
2. Alternative Approach: If active subscriptions exist, you must first deactivate the bundle instead of deleting it
3. Shop Ownership: You can only delete bundles that belong to your authenticated shop
4. Irreversible: Once deleted, the bundle configuration cannot be recovered
5. Clean Deletion: Only bundles with zero associated subscriptions can be permanently removed

Deletion Workflow:

1. Request deletion of bundle with ID
2. System checks for shop ownership
3. System counts active subscriptions using this bundle
4. If subscriptions exist → Returns error with subscription count
5. If no subscriptions → Deletes bundle permanently
6. Returns success (204 No Content)

When Deletion is Blocked: The system will prevent deletion and return a 400 error if:

• One or more active subscriptions are using this bundle
• The error message will include the exact count of active subscriptions
• Example: "Deleting Build-A-Box is not possible, 47 subscriptions found. You may deactivate the Build-A-Box."

Recommended Workflow for Active Bundles: If you want to stop offering a bundle that has active subscribers:

1. Update the bundle to set active: false (this prevents new subscriptions)
2. Monitor existing subscriptions until they naturally expire or are cancelled
3. Migrate customers to a different bundle if needed
4. Delete the bundle once all subscriptions have been resolved

Use Cases:

• Testing Cleanup: Remove test bundles created during development
• Failed Configurations: Delete bundles that were incorrectly set up
• Seasonal Offerings: Remove time-limited bundles after the season ends (if no subscriptions)
• Product Discontinuation: Clean up bundles for discontinued product lines
• Duplicate Bundles: Remove accidentally created duplicate configurations

Best Practices:

• Check Before Deleting: Always verify no active subscriptions exist
• Use Deactivation First: Set bundles to inactive before attempting deletion
• Document Changes: Keep records of when and why bundles were deleted
• Backup Configuration: Save bundle settings before deletion for potential recreation
• Communicate Changes: Inform team members about bundle removals
• Consider Archiving: For historical reference, deactivate rather than delete when possible

What Happens After Deletion:

• Bundle configuration is permanently removed from the database
• Bundle ID becomes available for reuse (though not recommended)
• Bundle handle becomes available for new bundles
• External integrations referencing this bundle will receive 404 errors
• Analytics and historical data may reference the deleted bundle ID

Error Prevention: Before attempting deletion, you can:

1. Query active subscriptions to check for bundle usage
2. Set the bundle to inactive status first
3. Wait for all subscriptions to complete or migrate customers
4. Then proceed with deletion

Authentication: Requires valid X-API-Key header or api_key parameter (deprecated)