OroCommerce quick start

Architecture note: hosted thin-client

The OroCommerce integration is different from our WooCommerce and Magento modules. Those are full local, mining + scoring + persistence all run inside your install. The OroCommerce bundle is a thin client: the engine runs on the MBA hosted backend at app.marketbasketanalysis.com, and the Oro bundle proxies + renders.

Why: Oro's B2B install footprint (CRM, marketing automation, RFQs, customer-specific catalogs) makes full- local heavy. Hosted thin-client ships in days, not months, and lets enterprise B2B customers consume MBA without taking on another long-running PHP workload inside their Oro app server.

Trust + data: the v1 thin-client uses license-key auth only, no order data leaves your Oro install. Mining runs against an aggregated item-pair frequency table that the bundle computes locally via Oro DBAL and ships to our backend (the hosted engine sees (sku_a, sku_b, co_occurrence_count) rows, never customer identifiers, never order IDs, never line items beyond SKU pairs). Full architecture and the privacy review at /privacy/first-party-architecture.

Prerequisites

• OroCommerce 6.0+ (Enterprise or Community)
• PHP 8.2 or 8.3
• PostgreSQL 14+ (the official Oro stack)
• Outbound HTTPS access to app.marketbasketanalysis.com
• An MBA Pro or Enterprise license key (this is enterprise-tier; no Starter on Oro)

1. Install via Composer

composer require marketbasketanalysis/orocommerce-bundle
bin/console oro:platform:update --env=prod --force
bin/console cache:clear --env=prod

oro:platform:update runs the bundle's migrations (the local item-pair frequency table + job ledger + API key store), wires the datagrids, and registers the storefront recommendation block.

2. Paste your license key

In the Oro admin, go to System → Configuration → MarketBasketAnalysis → License & tier. Paste your key (starts with mba_pro_ or mba_ent_), save. The bundle validates against our hosted backend on save; on success, the recommendations and substitutions surfaces light up under Marketing → MBA Reports.

3. Run your first mining job

From the command line:

bin/console mba:run-job --window=90

Or from the admin: Marketing → MBA Reports → Jobs → New Job. The bundle computes the item-pair frequency table locally, ships the aggregated rows to the hosted backend, and the hosted engine returns ranked opportunities. Typical end-to-end runtime: 30, 90 seconds for catalogs up to ~100k SKUs.

4. Review opportunities + substitutions

Three datagrids land under Marketing → MBA Reports:

• Opportunities, ranked bundle + cross-sell candidates with confidence, lift, estimated profit.
• Substitutions, swap targets for out-of-stock or EOL SKUs, the core B2B substitution use case.
• Jobs, mining run history, status, rule counts, durations.

5. REST proxies + storefront wiring

The bundle exposes thin REST proxies on your Oro app domain so your storefront, your CRM workflows, and external agents can hit one endpoint and not worry about which side (Oro vs hosted) does the lookup:

# Recommendations for an Oro product (by Oro product ID)
curl -H "X-API-Key: mba_pro_..." \
  "https://your-oro-store.example.com/api/marketbasketanalysis/recommendations/42"

# Substitutions for an out-of-stock SKU
curl -H "X-API-Key: mba_pro_..." \
  "https://your-oro-store.example.com/api/marketbasketanalysis/substitutions/42"

The Oro storefront ships with a Frequently Bought Together block (Layout Update XML, drop it into product_view via the standard Oro theme override). The block hits the proxy internally, so customer browsers never see the hosted backend.

For B2B, the bundle also wires RFQ pre-fill, when a sales rep starts a Request-for-Quote on an Oro product, the quote builder suggests substitutes (for out-of-stock) and cross- sells (for upsell) based on the same opportunity table.

6. Billing (Stripe webhook tier mapping)

Tier upgrades land via a Stripe webhook at /webhook/marketbasketanalysis/stripe. When you upgrade from Pro to Enterprise (or add seats), Stripe posts the subscription change and the bundle flips the cached tier without you needing to repaste the license key. The webhook path must be excluded from your Oro OAuth firewall, see Troubleshooting below.

7. MCP setup

The MCP server connects directly to the hosted backend with your license key, no per-store-hash wiring needed for Oro:

{
  "mcpServers": {
    "marketbasketanalysis": {
      "command": "npx",
      "args": ["-y", "@marketbasketanalysis/mcp"],
      "env": {
        "MBA_API_KEY": "mba_pro_...",
        "MBA_TENANT": "oro-yourstore"
      }
    }
  }
}

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

Pricing

• Pro, $199/month, full feature set, REST proxies, MCP access, AI bundle copy, B2B intelligence.
• Enterprise, custom, dedicated tenancy + SLA + multi-org Oro topologies + on-prem hosted-engine option. Talk to us.

OroCommerce is enterprise/B2B-focused, there's no Starter tier on Oro. If you're evaluating MBA without an Oro install, the Magento or WooCommerce Starter tiers ($49) are the cheapest path in.

Troubleshooting

• “Datasource shape rejected” on the Opportunities datagrid, Oro's datagrid YAML validator is strict about column types. If you customized the grid via datagrids.yml, every column listed in source.query.select must also appear in columns. Diff against the bundle's shipped YAML.
• Can't find the MBA tab in System Configuration, Oro builds the system_configuration tree from per-bundle config tree YAML at cache warm. If the tab doesn't appear after install, run bin/console cache:clear --env=prod (not just cache:warmup, the tree is built only on full clear).
• Stripe webhook returns 403 (CSRF / firewall), Oro's default firewall config protects all POST routes with the OAuth firewall. The Stripe webhook path /webhook/marketbasketanalysis/stripe must be excluded. The bundle ships a firewall override under security.yaml, but if you have a global override that wins by load order, re-add the explicit exclude: ^/webhook/marketbasketanalysis/.
• License key validates locally but recommendations return 401, the validation cache TTL is 24h; if you recently switched keys, run bin/console mba:license:refresh to invalidate.

See also

• REST API reference
• MCP server setup
• Mining engines (the hosted backend exposes the same four engines as the full-local platforms)
• OroCommerce platform page (positioning, B2B fit, RFQ workflow)
• First-party architecture (what data crosses the thin-client boundary, and what doesn't)
• Need install help? Talk to us.