Guides
Start typing to search…
  1. Custom Bundles

Sell and edit BYOB using storefront bundle APIs

This guide explains how to implement a custom build your own bundle (BYOB) experience using Loop bundle APIs to sell and update subscription bundles from a custom storefront experience.

Overview:

Loop provides a bundle API suite that can be used to build a custom BYOB bundle experience outside the default Loop bundle builder. These APIs support both:

  • selling subscription bundles
  • updating subscription bundles after purchase

The bundle API suite consists of 7 APIs that power the complete BYOB lifecycle across bundle discovery, configuration, checkout creation, and bundle editing.

Sell a subscription bundle

The following APIs are required to sell a subscription bundle using a custom bundle builder experience.

  1. List bundles - Retrieve a list of all active bundles configured in Loop Admin.

Use this API when building a bundles listing page where customers can browse available bundle options before selecting one.

Use case: Featuring a landing page listing all the bundles a store offers. Example bundles listing page.

  1. Read bundle details - Retrieve configuration details for a specific bundle.

The response includes:

  • boxSizes
  • sellingPlans
  • products
  • discounts (if configured)
  • categories (if configured)

Use this API to build the bundle selection interface where customers choose products within the bundle rules.

  1. Create bundle transaction - A bundle transaction must be created before adding a bundle to the cart.

This API generates a transaction ID that represents the selected bundle configuration.

Create a transaction every time a customer adds a bundle to the cart or checkout. This ensures Loop receives the latest bundle configuration selected by the customer.

After receiving the transaction ID, attach it to bundle line items in the Shopify cart request using: _bundleId: txnId

The property key must be _bundleId. If a different key is used, Loop will not process the line items as bundle items.

  1. Read translations - Fetch bundle translations for a specific locale.

Use this API when building multilingual bundle selection experiences.

  1. Read preferences - Fetch bundle preferences configured in Loop Admin.

This API returns bundle configuration preferences that help control bundle selection behavior in the custom bundle builder experience.

Add bundle to Shopify cart

After generating the bundle transaction ID:

Attach the _bundleId property with the transaction ID to all bundle line items in the Shopify cart request.

API endpoint (POST) - /cart/add.js

Passing _bundleId ensures:

  • bundle selections remain grouped correctly
  • discounts apply correctly
  • bundle metadata is preserved during checkout
  • Loop creates a subscription bundle instead of separate subscription line items

Update a subscription bundle

Customers can edit previously purchased bundles using a custom bundle editing experience powered by Loop bundle editing APIs.

These APIs support editing bundles from:

  • Loop subscription portal redirects
  • custom subscription portals
  1. Subscription bundle details - Fetch details of the bundle configuration that the subscriber wants to edit.

When customers are redirected from Loop’s subscription portal to the configured custom edit bundle page, the redirect URL includes:

transactionId
token

Use these values to retrieve bundle configuration details.

If building a custom subscription portal:

  1. retrieve _bundleId from subscription line item properties using the subscription details API
  2. generate an access token using the token generation API
  3. pass transactionId and token to fetch bundle details
  1. Update subscription bundle - Update bundle selections after the subscriber modifies bundle contents.

Pass the accessToken in the request headers for authentication.

After successful bundle update, the API returns a: returnUrl

This URL can be used to redirect the subscriber back to the subscription portal if required.

Updating the bundle ensures future renewals reflect the modified bundle configuration selected by the subscriber.

Summary

To implement sell and edit BYOB bundles using a custom bundle builder experience:

  1. list available bundles
  2. read bundle configuration
  3. allow customers to select bundle items
  4. create bundle transaction
  5. attach _bundleId to cart line items
  6. add bundle to Shopify cart
  7. fetch bundle configuration for edits
  8. update bundle selections using editing APIs

If you need any assistance with the implementation, please reach out to our support team at [email protected] .

Updated 2 days ago