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

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)

Fetches comprehensive Build-A-Box bundle configuration using a user-friendly handle (URL slug) instead of numeric ID. This endpoint is specifically designed for customer-facing storefronts and integration scenarios where you want to reference bundles by their human-readable handles rather than database IDs.

Key Differences from GET /{id}:

• Lookup Method: Uses bundle handle (e.g., 'premium-coffee-box') instead of numeric ID (e.g., 12345)
• Response Format: Returns SubscriptionBundlingResponseV3 with enhanced structure
• Customer Focus: Optimized for storefront display and customer selection workflows
• Bundle + Subscription: Returns both bundle details AND associated subscription plan information
• Public Access: Designed for integration in customer-facing applications

What is a Bundle Handle? A handle is a URL-friendly identifier for a bundle:

• Format: lowercase letters, numbers, and hyphens only
• Example: premium-coffee-selection, monthly-snack-box, beauty-essentials
• Stable: Unlike IDs, handles remain consistent across environments
• SEO-Friendly: Can be used in customer-facing URLs
• Human-Readable: Easy to remember and communicate

Response Structure (SubscriptionBundlingResponseV3):

{
  "bundle": {           // Complete bundle configuration
    "id": 45678,
    "bundleName": "Premium Coffee Selection",
    "bundleHandle": "premium-coffee-selection",
    "description": "...",
    "products": [...],
    "pricing": {...},
    "active": true
  },
  "subscription": {     // Associated subscription plan details
    "planId": 98765,
    "frequencies": [...],
    "deliveryOptions": {...},
    "sellingPlan": {...}
  }
}

Primary Use Cases:

1. Storefront Integration: Display bundle details on product pages
2. Customer Portal: Allow customers to browse available bundles
3. Landing Pages: Create dedicated pages for specific bundles using handles
4. Marketing Campaigns: Link directly to bundles with memorable URLs
5. Cross-Platform Sync: Use stable handles for multi-platform integrations
6. Mobile Apps: Retrieve bundle data using consistent identifiers
7. External Integrations: Third-party systems can reference bundles by handle

When to Use Handle vs ID:

• Use Handle when:

  • Building customer-facing features
  • Creating shareable URLs
  • Syncing across environments (dev → staging → prod)
  • External systems need stable references
  • SEO and user experience are priorities

• Use ID when:

  • You already have the numeric ID from another API response
  • Performing administrative operations
  • Internal system integration
  • Optimizing for query performance

Availability Validation: The endpoint validates that:

• Bundle exists and belongs to the specified shop
• Bundle has an associated subscription configuration
• If validation fails, returns 404 Not Found
• Both bundle AND subscription must be present for success response

Integration Examples: Storefront Display:

// Fetch bundle for display on product page
const handle = 'premium-coffee-selection';
const response = await fetch(
  `/api/external/v2/build-a-box/${handle}`,
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { bundle, subscription } = await response.json();
displayBundleOptions(bundle, subscription);

Best Practices:

• Handle Naming: Use descriptive, SEO-friendly handles
• Caching: Cache bundle data with handle as key for better performance
• Error Handling: Always check for 404 - bundle may be deleted or deactivated
• Environment Sync: Use handles to maintain consistency across environments
• URL Structure: Incorporate handles into clean, readable URLs
• Documentation: Document handle conventions for your team

Performance Considerations:

• Handle lookups may be slightly slower than ID lookups
• Response includes full bundle + subscription data (larger payload)
• Consider caching for frequently accessed bundles
• Returns complete product catalog for the bundle

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