Market Basket Analysis: Profit-Aware Bundle Ranking with Explainable Math

Install the embedded app, approve the recurring charge, run your first mining job, drop the FBT widget on a product page. ~10 minutes start to first recommendation.

Getting started: the setup wizard

The first time you open the app after install, MarketBasketAnalysis launches a guided setup wizard. It walks you through setup in order of impact, so you reach your first live recommendation quickly. The steps further down this page are the same ones the wizard covers, in the same order. The review step shows product images next to each mined pair, so you sanity-check suggestions at a glance before anything goes live.

The wizard is order aware. It checks how many paid orders your Shopify store has in the trailing 90 days and points you at the fastest path to value:

30 or more paid orders, the wizard sends you to Run your first mining job. There is enough history to mine statistically meaningful product pairs.
Few or no orders, the wizard offers the AI catalog path instead: the AI catalog engine uses your own AI key and is available on all plans, so you generate bundles from catalog-based recommendations on day one, with no order history required. See AI features.

Every step is optional. Click Skip this step to move on, or I'll finish later to exit. The app remembers exactly where you stopped, so you resume in the same place next time. While setup is unfinished, the dashboard shows a Finish setup banner with a resume link.

You can re-run the wizard at any time, even after finishing it. Use Re-run setup on the dashboard at any time, even after finishing, to clear your setup progress and reopen the wizard from the top.

Prerequisites

Shopify store on any plan (Basic through Plus)
Shopify admin user with permission to install apps
At least ~200 orders in your chosen window for meaningful patterns
Online Store 2.0 theme (required for the storefront FBT app block; post-purchase extension works on any theme)

Permissions and scopes

During OAuth, Shopify asks you to approve these access scopes. The app requests the minimum it needs:

read_orders, to pull order history for mining (the most important scope, mining cannot run without it).
read_products and write_products, to read the catalog and create native Bundle products and bundle copy.
read_customers, for per-customer reorder predictions.
read_inventory, so bundle inventory and the catalog hygiene scanner can reason about stock on hand.

Only a Shopify staff account with the Apps and channels permission can install the app and approve these scopes. The app also registers the mandatory GDPR webhooks (customers/data_request, customers/redact, shop/redact) plus app/uninstalled and orders/create (the velocity re-mine trigger).

Marketplace support: the OAuth install flow and the mandatory GDPR webhooks are Shopify only. Shopify uses expiring offline access tokens that the app refreshes automatically, where BigCommerce issues long-lived tokens that never expire. WooCommerce, Magento, and OroCommerce install as a plugin, module, or composer bundle and have no OAuth handshake. On those platforms you configure a license key instead.

1. Install

We're currently in early access via Custom Distribution; the public App Store submission is in preparation. Request a direct install link from /contact and we'll email you a Partner-Dashboard install URL (typically within one business day). The install flow is identical to the eventual App Store flow, OAuth + billing approval, just scoped to your specific store.

2. Approve billing

Billing runs through the Shopify Billing API, no separate Stripe checkout. After OAuth, Shopify shows the recurring charge approval screen with a 14-day free trial:

Plus, $99/month, one plan. It unlocks the whole product: the FBT widget, post-purchase extension, native Bundles, the Bundle Builder, Shopify Functions cart upsell, AI bundle copy, the ai_catalog engine, REST API + MCP access, and feed exports.

Before you approve the charge you run on the Free tier, which already includes every mining engine, recommendations, substitutions, native Bundles, the theme FBT block, the REST API, and the MCP server. Approving Plus adds the surfaces listed above.

Test stores and Partner-owned dev stores get the charge in test mode automatically, no real money moves until you launch.

Marketplace support: billing is Shopify only behavior. Shopify collects payment natively through the Billing API at a single $99/month flat Plus plan. BigCommerce bills the same product through Stripe, and WooCommerce, Magento, and OroCommerce use Stripe plus a license key. The plans are the same on every platform: Free ($0) and Plus ($99/month flat), metered on capability and compute, never on GMV.

3. Run your first mining job

The embedded admin opens to the Jobs page. Click Run now. Default engine is co_occurrence, default window is 90 days. The job pulls orders via the Shopify Admin GraphQL API, mines pair + bundle rules, and writes the resulting opportunities back to the embedded app. The default engine runs inline on your order data. Only the revenue-weighted hosted_hui engine offloads to MBA hosted infrastructure (Plus). You can change the engine and thresholds in Settings → Mining or per run.

Each run gets a friendly Job #N handle and a live progress panel: status, runtime, orders scanned, and rules emitted update in place while the job runs, so you are never staring at a spinner wondering what is happening.

Typical runtime: 30, 90 seconds for stores with up to 50k orders. Stores with 100k+ orders run async, you'll get an in-app notification when the job finishes.

Marketplace support: mining runs on all marketplaces, with platform differences. Shopify runs jobs synchronously and drains an async queue for stores past 100k orders. BigCommerce runs synchronously with no queued path, WooCommerce runs async through Action Scheduler / WP-Cron, and Magento runs through its own queued cron runner. Engine availability also differs: see the comparison under mining engines below.

Mining engines on Shopify

Pick the engine in Settings → Mining or per run on the Jobs page. Shopify supports these engines:

co_occurrence, the default, runs locally on your order history. No license required.
seasonal_cohort and return_aware, local variants that weight pairs by recency / season and downweight high-return pairs. No license required.
ai_catalog, the cold-start engine. It uses your own AI key and is available on all plans, including the free tier, so a new store with no order history can still generate bundles.
hosted_hui, the revenue-weighted FP-Growth / high-utility-itemset engine. It runs on MBA hosted infrastructure and is Plus gated. Reach it through the hosted hui-mine API or the mine_hui_itemsets MCP tool.

If you select a Plus engine on the Free tier, or an AI engine with no key, the run falls back to co_occurrence and notes the fallback in the run diagnostics. A run never hard-fails because of an engine choice.

Marketplace support: engine names and tiers differ by marketplace. On Shopify the FP-Growth / HUI engines run hosted (the local sql_pairs and local fp_growth engines that BigCommerce and WooCommerce run on-box are reached through hosted_hui here), and the ai_catalog engine is free on Shopify and WooCommerce but Plus gated on BigCommerce, Magento, and OroCommerce. Every marketplace falls back to co-occurrence when an unlicensed Plus engine is requested, except WooCommerce HUI, which raises an error instead. The seasonal_cohort and return_aware engines ship on Shopify, BigCommerce, WooCommerce, and Magento, not on OroCommerce. See the engines reference for tuning.

4. Frequently Bought Together (and other storefront surfaces)

Before you ship, review the candidates in Opportunities. Every grid row shows both the product name and SKU on each side of the rule, plus score, confidence, and lift, and you can run bulk actions (approve, dismiss, pin) across a selection. Then ship via three surfaces, all backed by the same opportunities:

Frequently Bought Together app block, in the theme editor, open a product template, click Add block → Apps → MBA Frequently Bought Together. Drop it under the buy box.
Post-purchase extension, served as a Checkout UI extension on the order status page. Enable from Settings → Checkout → Post-purchase page in the Shopify admin (one-time, store-level).
Native Bundles, approve any pair-bundle opportunity and the app creates a real Shopify Bundle product (via the Bundles API) you can review before publishing. Bundle inventory tracks the component SKUs automatically.

Also available on Shopify: a one-click post-purchase upsell on the order-confirmation surface (ungated), A/B testing on your recommendation surfaces, an opt-in cart drawer with an AOV progress bar and in-cart upsells, and the expanded bundle formats (BYOB, volume / quantity breaks, BOGO, virtual).

Marketplace support: the storefront surfaces ship on all marketplaces, but the injection mechanism is platform specific. Shopify uses theme app extensions (Online Store 2.0), an app proxy, and Checkout UI extensions. BigCommerce uses the Scripts API, WooCommerce uses shortcodes and Gutenberg blocks, and Magento uses Hyva and Luma blocks. Two Shopify limits to note: the in-checkout bundle suggestion is Shopify Plus only (it renders through a Checkout UI extension), and the Bundle Builder and post-purchase upsell are Plus plan. The post-purchase order-status recommendation block itself is ungated. The no-code Offer Builder template gallery is available on Shopify and BigCommerce only.

5. REST API examples

The Shopify app exposes the same shape as our other platforms. Mint an API key from Settings → API keys in the embedded admin (Plus plan only). The key is shown once at creation and starts with mba_live_. Then:

# Get recommendations for a product (by Shopify product ID)
curl -H "Authorization: Bearer mba_live_..." \
  "https://app.marketbasketanalysis.com/api/v1/recommendations?\
shop=mystore.myshopify.com&product_id=7891234567890"

# Find substitutes for an out-of-stock SKU
curl -H "Authorization: Bearer mba_live_..." \
  "https://app.marketbasketanalysis.com/api/v1/substitutions?\
shop=mystore.myshopify.com&product_id=7891234567890"

Beyond recommendations and substitutions, the Shopify app also serves /api/v1/rationale (with an impression beacon), /api/v1/forecast/bundle-inventory, per-customer reorder-predictions (Plus), the hosted hui-mine job API, the Partner Recommendations API, and the ACP (agentic-commerce) endpoints with .well-known discovery. Full reference at /docs/api.

Marketplace support: the GET /recommendations and GET /substitutions contract is shared across all marketplaces, but the auth model differs. Shopify, BigCommerce, and WooCommerce use a Bearer mba_live_ key. Magento uses an admin integration access token, and OroCommerce inherits the platform OAuth2 firewall. The full ACP ProductsResponse plus discovery surface is Shopify only, and a second, tiered paid recommendations namespace exists only on WooCommerce, Magento, and OroCommerce, not on Shopify or BigCommerce.

6. MCP setup (Plus)

Wire your Shopify store into Claude Desktop, Claude Code, Cursor, or any MCP host. Add the npm package and your API key:

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_pro_...",
        "MBA_SHOP": "mystore.myshopify.com"
      }
    }
  }
}

Full host-by-host setup at /docs/mcp.

Troubleshooting

Mining job not starting, the most common cause is the Admin GraphQL read_orders scope being denied during OAuth. Reinstall the app and accept all requested scopes; the job will pick up automatically on the next tick.
Billing stuck in test mode, expected on Partner-owned dev stores and trial stores, Shopify never charges those. On a live store, if the recurring charge shows as test in Settings → Plan → Subscriptions, uninstall and reinstall, the embedded app calls appSubscriptionCreate with test: false when the store is live.
Embedded app shows a blank screen, almost always a Content Security Policy issue. Shopify requires the embedded app to set frame-ancestors https://*.myshopify.com https://admin.shopify.com. If you've customized your store's CSP via a theme or another app, allowlist app.marketbasketanalysis.com.
App block missing in theme editor, the FBT app block only appears on Online Store 2.0 themes. On legacy themes, use the post-purchase extension (theme-agnostic) or migrate to 2.0.

Features reference

A reference for every page in the embedded admin, what it does and when to use it. The sidebar groups these as Insights, Storefront offers, Experiments, and More. The settings behind these features live in the configuration reference.

Each entry below notes its Marketplace support: All marketplaces when the feature ships everywhere (the implementation can differ per platform), Shopify only when it is exclusive to this app, or a specific list. Where Shopify differs from the other apps, a short note calls it out.

Settings and configuration

The embedded admin's sidebar (rendered by the Shopify admin chrome) lists the high-traffic pages directly: Weekly plan, Opportunities, Substitutions, Bundle builder, Mining jobs, Performance, AI merchandiser, Settings, and API keys, with More features opening the full grouped directory (Insights, Storefront offers, Experiments, and More, which holds Settings, API keys, Integrations, Autonomous agent, Diagnostics, and Billing) and Request a feature pinned last. This section maps the highest-traffic configuration topics to where each one lives in the Shopify app. For what every setting means (the values are shared across all five platforms), see the configuration concept reference.

Mining thresholds

Open Settings from the app sidebar to pick the default engine and tune min support, min confidence, min lift, and max itemset size. The Mining jobs page shows the resolved values next to each run, and lets you override them per job. The mining engines section covers the engines; the thresholds themselves are explained in the concept reference.

Scheduling

The mining schedule is on the same Settingspage: turn auto-mining on, pick a cadence, and set the order-history window. Because the Shopify app is hosted, the schedule fires from the app's own always-on scheduler; there is no cron or external service to configure. The order-velocity trigger re-mines reactively when enough new orders land between scheduled runs. See the scheduling concepts for how the triggers combine.

Weekly plan

Weekly plan is the first item in the app sidebar: your ranked actions for the week, each with a short rationale. Its AI narration uses the provider key you save in Settings; with no key it falls back to deterministic copy. The weekly digest email is configured in Settings too, so the same plan can land in an inbox on your planning day. Concepts: weekly plan and weekly digest email.

Integrations

More features → Integrations is the connector hub for Slack, Klaviyo, HubSpot, Salesforce, Notion, and Linear. Each connector shows its connection status and a connect, finish-setup, or manage action. Per-connector behavior is in the integrations concepts.

Autonomous agent

More features → Autonomous agent is where you opt into the merchandising agent and review its approval queue. The agent is off by default; every proposed action waits for your approval, and approved actions carry revenue-lift attribution. Concepts: autonomous purchasing.

Diagnostics

More features → Diagnosticsopens the Diagnostics page: the latest run's effective config, the event log, and the support export. The next section covers it in detail; the plan gating is in the diagnostics concepts.

Diagnostics and transparency

A support-and-trust surface for every mining run. The basic view shows the latest run's details and a recent-events summary and is available on every tier. The deep view adds the full, filterable event log (filter by level, category, job, or time) and is Plus. Use it to confirm which engine actually ran, read any fallback notes, and trace why a run produced the rules it did.

Marketplace support: All marketplaces. The basic view is free everywhere and the deep view is Plus on BigCommerce, WooCommerce, Magento, and OroCommerce as well.

Dashboard

The home page of the embedded admin. It shows four at-a-glance metrics, when mining last ran, how many opportunities are active on the storefront, how many bundles you have pushed, and the current mining window, plus your top five opportunities and quick actions to run mining or browse opportunities. New stores see an onboarding wizard here that walks through the first mining run. Use it as your daily starting point to see whether anything needs attention.

Marketplace support: All marketplaces.

Billing

Shows your current plan (Free or Plus), what it unlocks, and your Shopify subscription status. Cancellations and plan changes happen in Shopify, so this page links you to Settings → Billing → Apps and subscriptions in your store admin rather than handling them in the app. Plus unlocks the Bundle Builder, post-purchase recommendations, feed exports, and reorder predictions. Open this page to confirm your plan or start a Plus upgrade.

Marketplace support: All marketplaces, with different billing rails. On Shopify, payment is collected by Shopify natively through the Billing API at one $99/month Plus plan. BigCommerce bills through Stripe, and WooCommerce, Magento, and OroCommerce use Stripe plus a license key.

AI merchandiser

A chat assistant that answers questions about your catalog and recommendations, for example which products pair well or what a good gift bundle would be. It can call the same recommendation and substitution tools the rest of the app uses, and it shows when it does so. You can save an answer as a note on your weekly plan. Use it when you want a quick read on the data without building a report.

Marketplace support: All marketplaces ship the tool-calling chat. Shopify renders the full chat surface in the embedded admin. WooCommerce and OroCommerce ship the chat service layer but not a merchant chat page yet, so the assistant there is reached through the API rather than a UI.

Performance

Closes the loop on bundles you have pushed: it pulls the last 30 days of Shopify orders and reports orders, units, revenue, and last-sold date per bundle, plus totals across all of them. Numbers are pulled live from the Shopify Admin API and are denominated in your store currency. Use it to see which pushed bundles actually sell so you can keep the winners and retire the rest.

Marketplace support: Bundle performance dashboards ship on Shopify, BigCommerce, and Magento. Unverified on WooCommerce and not present on OroCommerce.

Personalization API

A dashboard for serving recommendations to your own front end through the personalization endpoints (homepage recommendations, search rerank, and subject picker). It shows your current tier, the monthly call cap and how much you have used, and per-endpoint call counts with p95 latency for the month. Use it when you render recommendations in a custom storefront or headless setup rather than the bundled widgets, and to watch your usage against the cap.

Marketplace support: Shopify and Magento. The personalization endpoints (homepage recommendations, search rerank, subject picker) ship with a dashboard on Shopify and as POST routes on Magento. BigCommerce and OroCommerce do not ship them, and on WooCommerce the personalization service is deferred with no route or page.

Catalog enrichment

Reviews AI-written suggestions for product fields, descriptions, image alt text, category tags, and SEO meta, on your lowest-quality listings. Each suggestion sits in a queue where you Apply, Skip, or edit it, and applying is the only action that writes to Shopify, gated behind a confirmation so a stray click cannot change your catalog. A monthly token meter tracks usage against your tier cap. Use it to fill gaps in thin listings that weaken both search and recommendations.

Marketplace support: Shopify, BigCommerce, WooCommerce, and Magento. It is not present on OroCommerce. The plan varies: on Shopify it is part of Plus.

Catalog hygiene

Scans your catalog for problems that weaken recommendations and tie up capital: dead SKUs (inventory on hand with no sales), duplicate listings, products missing a reorder threshold, and mis-categorized products missing peer tags. Each issue carries a severity and a one-line summary, and the top issues also surface in your weekly plan where you can approve a fix. Run it periodically to keep the catalog clean.

Marketplace support: Shopify only. The standalone catalog hygiene scanner is exclusive to this app.

Cross-store

For operators who run more than one store, this links sister shops so you can compare them and surface patterns that are only strong when the stores are combined. You link shops with a one-shot token that expires after seven days and never carries a shop identifier: issue it on one store, paste it into the other. It then shows a per-shop comparison and the top cross-store patterns. The page appears once you are eligible for a multi-store group.

Marketplace support: Shopify and OroCommerce. Both ship the multi-store link, the seven-day token redeem, and the cross-store bundle scanner. It is not present on BigCommerce, WooCommerce, or Magento.

Drift alerts

A read-only list of alerts that fire when the hosted and local mining engines produce results that diverge by more than 20% on the same dataset. Each row shows when it fired, the divergence percentage, and a short summary. A persistent run of alerts usually points to a margin-data outage or a math regression, so check it if your recommendations look off and you want to confirm the engines agree.

Marketplace support: Shopify and BigCommerce surface drift alerts, including via the /api/v1/drift-alerts route. Coverage on WooCommerce, Magento, and OroCommerce is unverified.

Returns insights

Ranks your products by return rate, counting only products with enough orders to be meaningful so a single return does not skew the list. Each row shows returns, orders, the rate, and a suggested action that scales with the rate, from monitor up to revising or archiving the listing. The data builds from the orders and refunds webhook. Use it to find the products and pairings driving returns.

Marketplace support: Shopify only as a standalone page. BigCommerce, WooCommerce, and Magento apply return-rate scoring through the return_aware engine but do not ship a dedicated Returns insights page.

LTV segments

Shows how your customers split across lifetime-value buckets (VIP, regular, new, at risk), with a count, share, and average score for each. The buckets fill in as the storefront serves recommendations to known customers, so the distribution grows over time rather than appearing all at once. Use it to understand the shape of your customer base before you target an offer.

Marketplace support: Shopify only.

Hosted mining

Telemetry for larger mining runs processed on our infrastructure rather than inline. It lists recent hosted jobs with their dataset hash, order count, duration, and a preview of the top itemsets, plus your hosted compute used in the last 30 days and the latest drift report comparing the hosted and local engines. The page is read-only. Use it to confirm a large run finished and to track hosted compute on the Plus plan.

Marketplace support: All marketplaces use the same hosted plane for HUI offload (Plus). The difference is how much runs hosted: Shopify, BigCommerce, WooCommerce, and Magento mine locally and offload only HUI, while OroCommerce is a thin client with no local miner, so every run proxies to the plane.

Request a feature

A simple in-app form for telling us what to build next. It emails our team your request along with your store, plan tier, app name, and a timestamp so we can follow up with the right context. There is an optional title and a category to help us route it. Use it whenever you hit a gap or have an idea, it goes straight to the people building the product.