The Loop Bundle API suite lets you build a fully custom bundle experience - selling a subscription bundle from your own storefront and letting customers edit that bundle after purchase from your own portal.
The suite has two groups of APIs:
- Sell a subscription bundle with a custom experience.
- Update a subscription bundle from a custom editing experience.
Sell a subscription bundle
Use these APIs to sell a subscription bundle from a custom experience.
Retrieve a list of all active bundles.
Use case: a landing page listing all the bundles a store offers. Example bundles listing page.
Read details for a specific bundle ID: boxSizes, sellingPlans, products, discounts (if any), and categories (if any).
Use case: the bundle builder page where customers select products for their bundle. Example bundle builder page.
You must create a bundle transaction to create a bundle subscription in Loop. If you don't, the line items are not bundled once the subscription is purchased - they remain separate items.
Create a transaction whenever a customer adds a bundle to the cart/checkout, so Loop always has the latest bundle data. Then add the returned txnId as the line-item property _bundleId: txnId for all bundle lines on the Shopify add.js call.
The property key must be exactly
_bundleId, otherwise Loop won't create the line as a bundle line.
When the customer edits the bundle in the cart (products, quantities, discount, box size, or selling plan), update the existing transaction in place - keeping the same txnId - instead of creating a new one and rewriting the cart line each time. This API is only applicable before purchase is completed
Fetch translations for a specific bundle in a particular locale, to localize your bundle UI.
Fetch bundle preferences as configured on the Loop admin portal (e.g. inventory display), to keep your UI consistent with the merchant's settings.
Update a subscription bundle (beta)
Use the APIs below to let a customer edit a bundle after purchase, from either Loop's subscription portal or a custom portal. These are access-gated - contact your account success manager to enable API access.
When a customer lands on the edit-bundle custom URL (configured in Loop admin), fetch the details of the bundle they want to edit by passing transactionId and token.
From Loop's subscription portal
Customers are redirected to the configured edit page with transactionId and token as URL query parameters, which you use to call the API.
From a custom subscription portal
Use the Read subscription details API to read any of the bundle line items and pass transactionId. Use the Generate access token API and pass the accessToken as token.
Update the subscription bundle based on the customer's new selection from a custom editing experience.
For authentication, pass the accessToken in the API headers (generated in the previous step). On success, the endpoint responds with a returnUrl you can use to redirect the customer back to the Loop subscription portal (if needed).
Don't confuse the two "update" APIs:
- Update bundle transaction edits a transaction before purchase (storefront-callable).
- Update subscription bundle edits a bundle after purchase (access-gated).
Before you start: key concepts
Most integration issues come from mixing up the three identifiers below. Read this first.
| Term | What it is | Where you get it |
|---|---|---|
Bundle ID (id) | The public identifier of a bundle definition, e.g. 49317797aa47477198b3cf7976f484aa. Used to read a bundle and to create a transaction. | id from List bundles / Read bundle details |
Transaction ID (txnId / transactionId) | A unique ID Loop gives you when a customer puts a bundle in their cart. It represents that one bundle. Create it once; if the customer changes the bundle before buying, update the same ID | Response of Create transaction |
_bundleId | The Shopify line-item property whose value is the txnId on every bundle line. This is how Loop links cart lines to a bundle. | You set it on the /cart/add.js call |
Do not confuse_bundleId(a line-item property whose value is thetxnId) with the internalloopBundleIdthat may appear elsewhere on subscription data. When creating a transaction, the path{id}is the Bundle ID, never an internal reference.
Bundle types: the type field is FIXED or RANGE.
FIXED= a Preset bundle - the customer adds an exact, pre-defined set of items.RANGE= a BYOB (Build Your Own Bundle) - the customer builds a bundle within min/max limits.
Authentication & access
| API group | APIs | Auth |
|---|---|---|
| Sell a bundle | List bundles, Read bundle details, Create transaction, Update bundle transaction, Read translations, Read preferences | Storefront-callable (no token). Identify the store with the myshopifyDomain query parameter where required. |
| Update a subscription bundle (beta) | Get subscription bundle details, Update subscription bundle | Access-gated. Pass the customer accessToken in the request headers. |
All responses use a common envelope:
{ "success": true, "message": "…", "data": { }, "code": "SUCCESS", "pageInfo": null }On errors, success is false, data is null, and code carries a machine-readable value (e.g. NOT_FOUND, UNPROCESSABLE_ENTITY). Always branch on code, not on the human-readable message.