> ## Documentation Index
> Fetch the complete documentation index at: https://bundles-docs.getappfox.com/product-bundles/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Use the Appfox REST API to list, create, update, and delete Shopify bundles, and to read bundle orders and analytics. FBT bundles are not supported yet.

The REST API gives you the same control over your bundles as the dashboard. [Create an API key](https://bundles-docs.getappfox.com/product-bundles/docs/settings/api-and-mcp.md) first, then send it with every request:

```bash theme={null}
curl "<your-app-url>/api/v1/bundles" \
  -H "Authorization: Bearer <your-api-key>"
```

`<your-app-url>` is shown on **Settings** → **API & MCP**. All requests and responses are JSON. Errors look like this:

```json theme={null}
{ "error": { "message": "Bundle not found" } }
```

## Endpoints

| Method and path | Access | Description |
| - | - | - |
| `GET /api/v1/bundles` | Read | List bundles. Filter with `status` (`ACTIVE` or `PAUSED`), page with `page` and `limit` (max 100). |
| `GET /api/v1/bundles/{id}` | Read | Get one bundle with its products and offers. |
| `POST /api/v1/bundles` | Write | Create a bundle. |
| `PATCH /api/v1/bundles/{id}` | Write | Update the fields you send. `products` and `offers` replace the whole list when included. |
| `DELETE /api/v1/bundles/{id}` | Write | Delete a bundle. Safe to repeat. |
| `GET /api/v1/orders` | Read | List orders that contained a bundle. Filter with `bundleId`. Customer details aren't included. |
| `GET /api/v1/analytics` | Read | Use `range=7d`, `30d` or `90d`, or `range=custom&start=YYYY-MM-DD&end=YYYY-MM-DD`. |

## List bundles

```bash theme={null}
curl "<your-app-url>/api/v1/bundles?status=ACTIVE&limit=2" \
  -H "Authorization: Bearer <your-api-key>"
```

```json theme={null}
{
  "bundles": [
    {
      "id": 42,
      "name": "Skincare duo",
      "title": "Buy both and save",
      "bundleType": "FIXED",
      "status": "ACTIVE",
      "products": [
        { "productId": "gid://shopify/Product/1234567890", "title": "Cleanser", "handle": "cleanser", "quantity": 1, "isPrimary": true, "defaultVariantId": null },
        { "productId": "gid://shopify/Product/2345678901", "title": "Moisturizer", "handle": "moisturizer", "quantity": 1, "isPrimary": false, "defaultVariantId": null }
      ],
      "offers": [],
      "startsAt": null,
      "endsAt": null,
      "createdAt": "2026-10-01T09:30:00.000Z",
      "updatedAt": "2026-10-08T14:12:00.000Z"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 1
}
```

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.

```bash theme={null}
curl -X POST "<your-app-url>/api/v1/bundles" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Skincare duo",
    "title": "Buy both and save",
    "bundleType": "FIXED",
    "status": "PAUSED",
    "products": [
      { "productId": "gid://shopify/Product/1234567890", "quantity": 1, "isPrimary": true },
      { "productId": "gid://shopify/Product/2345678901", "quantity": 1 }
    ],
    "offers": [
      { "title": "Both", "subTitle": "", "tag": "", "label": "", "selected": true, "order": 0, "discountType": "PERCENTAGE", "quantity": 1, "value": 10 }
    ]
  }'
```

The response is `201` with the created bundle:

```json theme={null}
{
  "bundle": {
    "id": 43,
    "name": "Skincare duo",
    "title": "Buy both and save",
    "bundleType": "FIXED",
    "status": "PAUSED",
    "products": [
      { "productId": "gid://shopify/Product/1234567890", "title": "Cleanser", "handle": "cleanser", "quantity": 1, "isPrimary": true, "defaultVariantId": null },
      { "productId": "gid://shopify/Product/2345678901", "title": "Moisturizer", "handle": "moisturizer", "quantity": 1, "isPrimary": false, "defaultVariantId": null }
    ],
    "offers": [
      { "title": "Both", "subTitle": "", "tag": "", "label": "", "selected": true, "order": 0, "discountType": "PERCENTAGE", "quantity": 1, "value": 10, "imageUrl": null }
    ],
    "createdAt": "2026-10-09T10:00:00.000Z",
    "updatedAt": "2026-10-09T10:00:00.000Z"
  }
}
```

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`.

```json theme={null}
{
  "mixMatchGroups": [
    { "id": "base", "title": "Base kit", "required": true, "minSelect": 2, "maxSelect": 2, "productIds": ["gid://shopify/Product/1", "gid://shopify/Product/2"] },
    { "id": "extra", "title": "Your extra", "required": false, "minSelect": 1, "maxSelect": 1, "productIds": ["gid://shopify/Product/3", "gid://shopify/Product/4"] }
  ]
}
```

* `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:

```bash theme={null}
curl -X PATCH "<your-app-url>/api/v1/bundles/43" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ACTIVE" }'
```

The response is `200` with the updated bundle in the same shape as above.

## Delete a bundle

```bash theme={null}
curl -X DELETE "<your-app-url>/api/v1/bundles/43" \
  -H "Authorization: Bearer <your-api-key>"
```

```json theme={null}
{ "id": 43, "deleted": true }
```

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

```bash theme={null}
curl "<your-app-url>/api/v1/orders?bundleId=42&limit=2" \
  -H "Authorization: Bearer <your-api-key>"
```

```json theme={null}
{
  "orders": [
    {
      "orderId": "gid://shopify/Order/9001",
      "orderNumber": "#1001",
      "bundleId": 42,
      "bundleName": "Skincare duo",
      "orderTotal": "126.00",
      "bundleTotal": "126.00",
      "bundleDiscount": "14.00",
      "purchasedAt": "2026-10-07T18:20:00.000Z",
      "createdAt": "2026-10-07T18:20:05.000Z"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 1
}
```

## Analytics

```bash theme={null}
curl "<your-app-url>/api/v1/analytics?range=7d" \
  -H "Authorization: Bearer <your-api-key>"
```

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

| Status | Meaning |
| - | - |
| `400` | The request is invalid. The message says what to fix, for example a missing field or a product that doesn't exist in your store. |
| `401` | The key is missing, wrong or revoked. |
| `403` | The key is read only. Create a key with write access. |
| `404` | The bundle doesn't exist in your shop. |
| `405` | The method isn't supported on this path. |
| `409` | The bundle changed while saving (retry), or the app isn't installed or needs to be reopened in the Shopify admin. |
| `422` | Publishing would exceed Shopify's 10KB bundle data limit. Target collections, use fewer products, or create the bundle as `PAUSED`. |
| `502` | The change was saved but syncing with Shopify failed. Repeat the request, or open the app and save the bundle again. |

> [!TIP]
>
> Need a field or endpoint that isn't here? Contact us at [support@getappfox.com](mailto: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`:

```json theme={null}
{
  "bundleType": "BOGO",
  "products": [],
  "bogoBuyCollectionIds": "gid://shopify/Collection/100",
  "bogoBuyQuantity": 2,
  "bogoGetCollectionIds": "gid://shopify/Collection/200",
  "bogoGetQuantity": 1,
  "bogoMaxApplications": 3
}
```

`GET /api/v1/bundles/{id}` returns these fields alongside the bundle's products and offers:

```json theme={null}
{
  "bogoBuyCollectionIds": "gid://shopify/Collection/100",
  "bogoBuyQuantity": 2,
  "bogoGetCollectionIds": "gid://shopify/Collection/200",
  "bogoGetQuantity": 1,
  "bogoMaxApplications": null
}
```

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.

```bash theme={null}
curl -X PATCH "<your-app-url>/api/v1/bundles/42" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"offerAfterAddToCart": true}'
```

The bundle in the response, and subsequent `GET /api/v1/bundles/42` responses, includes:

```json theme={null}
{ "id": 42, "offerAfterAddToCart": true }
```

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.

```bash theme={null}
curl -X PATCH "<your-app-url>/api/v1/bundles/42" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"exitIntentOffer": true, "exitIntentDiscountCode": "STAY10"}'
```

The bundle in the response, and subsequent `GET /api/v1/bundles/42` responses, includes:

```json theme={null}
{ "id": 42, "exitIntentOffer": true, "exitIntentDiscountCode": "STAY10" }
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.