Skip to main content
The REST API gives you the same control over your bundles as the dashboard. Create an API key first, then send it with every request:
<your-app-url> is shown on Settings → API & MCP. All requests and responses are JSON. Errors look like this:

Endpoints

List bundles

Each bundle also includes its display and targeting settings (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.
The response is 201 with the created bundle:
Bundle rules match the dashboard:
  • 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 set targetType to ALL_PRODUCTS. Use countingMode COMBINED when mixed products from a collection should count toward the same tier. Creating a Volume bundle without countingMode defaults to COMBINED when it targets collections, all products, or more than one product, and PER_PRODUCT otherwise. Existing bundles keep the stored mode.
  • Mix & Match bundles need at least one product or collectionIds.
  • Mix & Match free gift: send mixMatchGift as an object (or JSON string) with unlock (BOX or GROUP), groupId (required for GROUP, and must match a group id), an optional title, and products: one to ten entries with a Shopify product GID in productId, a title, optional handle and imageUrl, and variants (id as a variant GID, title, available). Send null to remove the gift. Only Mix & Match bundles can have a gift. Invalid gifts return 400.
  • Mix & Match groups: send mixMatchGroups as an array (or JSON string). Each group has a unique id, title, required boolean, integer minSelect / maxSelect, and productIds containing Shopify product GIDs. Assign every product exactly once. Groups cannot be combined with collectionIds. Limits must fit the group’s product count; a required group includes every product once. The API derives minProducts and maxProducts from the groups. Send [] to remove groups. Invalid groups return 400.
  • bundleType can’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:
The response is 200 with the updated bundle in the same shape as above.

Delete a bundle

If the request returns 502, the bundle was deleted but Shopify wasn’t updated. Send the same request again to finish the sync.

List orders

Analytics

The response has a 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

Need a field or endpoint that isn’t here? Contact us at support@getappfox.com.

BOGO collection sides

For BOGO bundles, use bogoBuyCollectionIds 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:
Set 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

Set offerAfterAddToCart 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.
The bundle in the response, and subsequent GET /api/v1/bundles/42 responses, includes:
For volume bundles, 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

Set exitIntentOffer 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.
The bundle in the response, and subsequent GET /api/v1/bundles/42 responses, includes:
A non-boolean 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.