<your-app-url> is shown on Settings → API & MCP. All requests and responses are JSON. Errors look like this:
Endpoints
List bundles
buttonText, badgeText, discountLabel, minProducts, maxProducts, targetType, combinesWith, customerAudience, excludeB2b, customerTagsInclude, customerTagsExclude, widgetOnlyDiscount and more). Bundles created from the dashboard may include more settings than the API accepts.
Create a bundle
You supply only the Shopify product IDs. The product title, handle, image and variants are loaded from your store.201 with the created bundle:
- Fixed bundles need at least two products.
- BOGO bundles need at least one primary product (
isPrimary: true) and one other product. - Volume bundles need a title on every offer, and either products,
targetCollectionIds(up to 25 collection GIDs; not expanded into product IDs), or both. You can also settargetTypetoALL_PRODUCTS. UsecountingModeCOMBINEDwhen mixed products from a collection should count toward the same tier. Creating a Volume bundle withoutcountingModedefaults toCOMBINEDwhen it targets collections, all products, or more than one product, andPER_PRODUCTotherwise. Existing bundles keep the stored mode. - Mix & Match bundles need at least one product or
collectionIds. - Mix & Match free gift: send
mixMatchGiftas an object (or JSON string) withunlock(BOXorGROUP),groupId(required forGROUP, and must match a groupid), an optionaltitle, andproducts: one to ten entries with a Shopify product GID inproductId, atitle, optionalhandleandimageUrl, andvariants(idas a variant GID,title,available). Sendnullto remove the gift. Only Mix & Match bundles can have a gift. Invalid gifts return400. - Mix & Match groups: send
mixMatchGroupsas an array (or JSON string). Each group has a uniqueid,title,requiredboolean, integerminSelect/maxSelect, andproductIdscontaining Shopify product GIDs. Assign every product exactly once. Groups cannot be combined withcollectionIds. Limits must fit the group’s product count; a required group includes every product once. The API derivesminProductsandmaxProductsfrom the groups. Send[]to remove groups. Invalid groups return400.
bundleTypecan’t be changed after creation. Frequently bought together (FBT) bundles can’t be created or changed through the API yet.
discountType is one of PERCENTAGE, FLAT, FIXED_PER_ITEM, FIXED_PRICE or FREE_GIFT.
On a Volume bundle, an offer can also give a free gift with that tier: send giftProductId and giftVariantId (Shopify GIDs), and optionally giftTitle and giftImageUrl (an HTTPS URL) for the storefront. Send both IDs or neither. Offers you read back always include these four fields, null when the tier has no gift.
A Volume bundle can list its gifts in their own widget section with progressiveGifts (boolean), giftSectionTitle and giftSectionSubtitle (text up to 191 characters, null for the built-in wording), hideLockedGifts, showLockedGiftLabel and showLockedGiftImage (booleans), and giftLayout (LIST, GRID or COMPACT).
On a Volume bundle, set scratchOff (boolean) on an offer to hide that tier’s discount behind a scratch-off in the widget until the shopper reveals it. Offers you read back always include it, false when it’s off. Sending true on another bundle type is rejected.
Set showProgressBar (boolean) on a Volume bundle to show a progress bar toward the next tier above the tiers.
Update a bundle
Send only what should change. This publishes a bundle:200 with the updated bundle in the same shape as above.
Delete a bundle
502, the bundle was deleted but Shopify wasn’t updated. Send the same request again to finish the sync.
List orders
Analytics
range (start and end as ISO timestamps), a summary for the whole shop, a bundles array with views, add-to-carts, orders, revenue, discount, conversion rate and ROI per bundle, and a daily series of revenue and orders.
Error codes
BOGO collection sides
For BOGO bundles, usebogoBuyCollectionIds and bogoGetCollectionIds (comma-separated collection GIDs, or null) to choose collections for either side. Set bogoBuyQuantity and bogoGetQuantity to integers from 1 to 100. A collection side replaces that side’s product rows; the other side can still use products.
For example, send these fields with your bundle name, title, status, and offers to POST /api/v1/bundles:
GET /api/v1/bundles/{id} returns these fields alongside the bundle’s products and offers:
bogoMaxApplications to an integer from 1 to 1000 to cap how many times a BOGO deal repeats in one order. It defaults to null, which repeats the deal for every full set in the cart. The field is returned on GET, and a value outside that range returns HTTP 400.
Invalid collection IDs or quantities return HTTP 400. Each BOGO side must have products or collections. An unknown bundle ID returns HTTP 404.
Offer an upgrade after Add to cart
SetofferAfterAddToCart to true on a volume or fixed bundle to show an upgrade offer after shoppers use the theme’s Add to cart. The default is false. FBT upgrades are configured in the dashboard because the API does not edit FBT bundles.
GET /api/v1/bundles/42 responses, includes:
upgradeTier chooses the tier the offer shows: NEXT (default, the smallest tier above the quantity the shopper added), HIGHLIGHTED (the tier preselected in the widget) or SPECIFIC (the tier whose quantity is upgradeTierQuantity, an integer from 1 to 1000). If the shopper already added that many, no offer is shown. If the tier was removed, the next tier up is offered. Any other upgradeTier or upgradeTierQuantity returns HTTP 400.
A non-boolean value returns HTTP 400. An unknown bundle returns HTTP 404. The existing schedule, customer targeting and theme setup still apply. In GET /api/v1/analytics, upgradeViews and upgradeAccepts appear in each bundle and in the summary; upgrade purchases contribute to the bundle’s existing revenue.
Offer a bundle when shoppers are about to leave
SetexitIntentOffer to true on a volume or fixed bundle to show it once per session to a shopper who is about to leave the product page without adding to cart. The default is false. exitIntentDiscountCode is an optional Shopify discount code, up to 60 letters, numbers, dots, dashes or underscores, applied at checkout when the shopper accepts. Send null or an empty string to clear it. The code is cleared when exitIntentOffer is false. The offer is not available for other bundle types.
GET /api/v1/bundles/42 responses, includes:
exitIntentOffer or a code that is too long or has other characters returns HTTP 400. In GET /api/v1/analytics, exitViews, exitAccepts and exitRevenue appear in each bundle and in the summary; exitRevenue is the part of revenue that came from lines the offer added.