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

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.

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)

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.

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)

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