# CBX on Magento 2 — Platform Guide

> > Audience: integrators and developers running CBX on Magento 2 · Scope: what is different about the Magento 2 edition — installation, the admin area, connec…

Source: CBX documentation, version 3.x (released). Canonical page: https://docs.configbox.at/docs/platform/magento2/magento2_platform_guide. Last updated 2026-08-01.

---
> **Audience:** integrators and developers running CBX on Magento 2 · **Scope:** what is different about the Magento 2 edition — installation, the admin area, connecting products, and which jobs Magento handles instead of CBX · **Last reviewed:** 2026-07-21
>
> **Store admins:** the task-oriented manual is the [Admin Guide](https://docs.configbox.at/docs/admin-guide/) —
> start with its [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/) section, which
> covers the division of labor and product connection in plain language. This document is the
> technical counterpart.

**TL;DR** — On Magento 2, CBX is the **configurator engine only**; Magento is the shop.
You build products, questions, rules and calculations in CBX (**Configbox >
Administration** in the Magento backend) and attach a CBX product to a Magento catalog
product via a **custom option of type "CBX Configuration"**. Cart, checkout, orders,
customers, emails, tax and currency are all Magento's — CBX's own commerce screens are
hidden on this platform. Updates ride on `composer` + `bin/magento setup:upgrade`.

---

## 1. Division of labor — what Magento owns, what CBX owns

This is the one table to internalize; it decides which parts of the general CBX
documentation apply to you. In one picture: CBX produces the configured item, and
everything from the cart onward is Magento's.

```mermaid
flowchart LR
    subgraph CBX ["CBX — configurator engine"]
        CONF["Pages · questions · answers<br>rules · calculations · visualization"]
    end
    subgraph MAG ["Magento — the shop"]
        SHOP["Catalog · cart · checkout · orders<br>customers · email · tax · currency"]
    end
    CONF -->|"configured item, via a custom option"| SHOP
```

| Concern | Owned by | Notes |
|---|---|---|
| Product configurator (pages, questions, answers, rules, calculations, visualization) | **CBX** | The whole [configurator-building reference](https://docs.configbox.at/docs/functional/configurator_building) applies unchanged. |
| Product catalog, listings, product pages | **Magento** | CBX's own product listings are not used. |
| Cart & checkout | **Magento** | The configured item goes into Magento's cart as a product with a custom option; Magento runs checkout. CBX has no storefront checkout here. |
| Orders & order management | **Magento** | Configured selections, SKUs and prices are embedded in the Magento order line item. CBX's Orders screen is hidden. |
| Customers & accounts | **Magento** | Shoppers are Magento customers/guests. CBX does not manage identities on this platform. |
| Transactional email | **Magento** | CBX sends **no email** on Magento — order confirmations etc. are Magento's. CBX's Notifications screen is hidden. |
| Tax | **Magento** | CBX reads the Magento product's tax class/rate so configurator prices match the store. |
| Currency & price display | **Magento** | Store currency and locale come from Magento's store configuration. |
| Languages | **Magento** (store views) | CBX derives its language list from the locales of your Magento store views; translatable CBX content gets one tab per store-view language. |
| Shipping & payment methods | **Magento** | CBX's shipping/payment screens are hidden. |
| Discounts & promotions | **Magento** (cart rules) | CBX pricing produces the item price; Magento cart price rules apply on top. |

## 2. Installing and updating

CBX ships as two Composer packages: `rovexo/configbox-magento2` (the Magento module,
`Rovexo_Configbox`) and `rovexo/configbox-php` (the platform-independent engine it depends on).

```bash
composer require rovexo/configbox-magento2
bin/magento module:enable Rovexo_Configbox
bin/magento setup:upgrade
```

The pieces layer like this — the module plugs CBX into Magento, the engine underneath
is platform-independent, and `setup:upgrade` is what touches the database:

```mermaid
flowchart TD
    CR["composer require rovexo/configbox-magento2"] --> MOD["Rovexo_Configbox<br>Magento 2 module"]
    MOD -->|"depends on"| ENG["rovexo/configbox-php<br>platform-independent engine"]
    SU["bin/magento setup:upgrade"] -->|"recurring setup step<br>applies CBX migrations"| DB[("CBX tables in<br>Magento's database")]
```

- **Database setup and every later schema/data update run inside `setup:upgrade`.**
  The module registers a recurring setup step that applies CBX's own migration
  scripts — there is no separate CBX installer or update button. After a
  `composer update` of the CBX packages, run `bin/magento setup:upgrade` as you
  would for any module.
- **PHP requirement:** the pricing/rule engine ships ionCube-encoded; the server needs the
  **ionCube Loader** matching your PHP version.
- **License:** CBX licenses are **domain-bound**. If the license is missing or expired,
  a notice dialog appears in the Magento backend with a link to enter a new key (license
  management lives in the CBX dashboard). Staging/dev hostnames need to be whitelisted
  for your key — contact Rovexo support with the hostname.
- **CLI:** the full `configbox:*` command suite is registered on `bin/magento` — cache
  clearing, migrations (`configbox:migrate`, `configbox:migrate:unblock`), reading/writing
  settings from scripts (`configbox:config:*`), and task running. See the
  [CLI commands reference](https://docs.configbox.at/docs/technical/cli_commands); the commands are
  identical on every platform, only the binary (`bin/magento`) differs.

## 3. The CBX area in the Magento backend

- **Menu:** a top-level **Configbox** entry with a single item, **Administration**. It opens
  the complete CBX admin (one embedded application) — dashboard, product tree,
  calculations, settings. There are no further Magento menu entries or grids.
- **Permissions:** one ACL resource (`Rovexo_Configbox::administration`) controls access —
  **all-or-nothing**. A role either gets the whole CBX area or none of it; there is no
  per-screen CBX ACL. Inside the area, CBX trusts the Magento backend login.
- **Nothing under Stores > Configuration.** CBX deliberately adds no section to
  Magento's system configuration. All CBX settings live in the CBX area's own
  **Settings** screen (or via `bin/magento configbox:config:*`).
- **Reduced menu compared to Joomla/WordPress:** because Magento owns commerce (§1), the
  CBX admin menu on Magento shows only **Dashboard, Products, Calculations,
  Settings**. Orders, Customers, Reviews, Product Lists, Countries/States, Shipping, Payment
  Methods, Store Information, Customer Fields and Notifications are hidden — those jobs are
  done in the corresponding Magento screens. The Settings screen likewise hides options that
  only make sense with CBX's own cart/checkout.

## 4. Making a Magento product configurable

A CBX product is attached to a Magento catalog product through a **custom option**:

1. Build the product in CBX first (Configbox > Administration > Products) — pages,
   questions, answers, rules, calculations, as in the
   [configurator-building reference](https://docs.configbox.at/docs/functional/configurator_building).
2. Edit (or create) the Magento product: **Catalog > Products > … > Customizable Options >
   Add Option**.
3. Set the option type to **"CBX Configuration"** (under the *rovexo* group) and pick
   the CBX product from the dropdown that appears.
4. Save. The configurator now renders automatically on that product's storefront page — in
   the product-options area, with the visualization in the media/gallery area. **No widget,
   CMS block or manual placement is needed** (or possible); the custom option is the only
   attachment point.

The attachment, in one picture — the custom option is the only link between the two
products, and it is also what makes the configurator appear on the storefront page:

```mermaid
flowchart LR
    MP["Magento catalog product"] --> CO["Customizable option<br>type: CBX Configuration"]
    CO -->|"selects"| CP["CBX product<br>built in the CBX admin"]
    MP -->|"renders automatically"| SF["Storefront product page<br>configurator in the options area,<br>visualization in the gallery area"]
```

The CBX↔Magento product link is kept in a mapping maintained on product save/delete,
and **survives product duplication** — duplicating the Magento product copies the link to the
same CBX product.

> **One CBX custom option per Magento product.** The product link supports exactly one
> CBX product; adding a second CBX option is not supported and silently keeps
> only one of the links.

## 5. What happens in cart, checkout and orders

When the customer adds a configured product to the cart, CBX stores the full
configuration in its own tables and writes a **summary into the Magento quote item's custom
option value**: the selected answers as formatted text, the answer **SKUs**, and the net/gross
totals. From there on the flow is pure Magento:

- The cart and checkout show the configured selections as the custom option's value; the
  item price is the CBX-calculated price (tax per the product's Magento tax class).
- The Magento **order** carries the same selection summary and SKUs on the line item — this
  is what fulfilment works from (answer SKUs are set on CBX answers; see the
  configurator-building reference).
- **Wishlists** work: the configuration is preserved when a configured product is added to a
  wishlist and later moved to the cart.
- There is no CBX order record to manage; do **not** look for orders inside the
  CBX area (the screen does not exist on Magento). Order status, invoices, credit
  memos, shipment and all emails are standard Magento.

The whole handoff as a sequence:

```mermaid
sequenceDiagram
    actor Shopper
    participant CBX
    participant Magento
    Shopper->>CBX: Configure product, add to cart
    CBX->>CBX: Store full configuration in CBX tables
    CBX->>Magento: Write summary to the quote item's custom option<br/>selections as text, answer SKUs, net/gross totals
    Shopper->>Magento: Cart, checkout, payment
    Magento->>Magento: Order line item keeps the summary and SKUs
    Note over Magento: Fulfilment, invoices, emails — standard Magento
```

CBX features that are part of its own checkout on other platforms — quotation/RFQ
flow, saved carts, CBX customer accounts, CBX reviews — are **not available** on
Magento; use Magento equivalents where they exist.

## 6. Storefront behavior notes

- **URLs:** CBX storefront requests (configurator AJAX etc.) all go through
  `<store-url>/configbox/index/index?controller=…&task=…` and carry Magento's `form_key`.
  There are no per-view "pretty" CBX URLs on Magento — relevant when reading logs or
  debugging with support.
- **Content Security Policy:** the module ships a CSP whitelist for the external hosts
  CBX may use (`*.shapediver.com` for 3D visualization, `*.fontawesome.com`,
  `*.configbox.at`, `data:` images). If you run a **custom** CSP setup in restrict mode and
  see blocked resources on configurator pages, check these hosts first.
- **Caching:** CBX caches product/configurator structure server-side (APCu when available,
  file cache otherwise). Normal admin edits invalidate caches themselves. After changing CBX
  data outside the admin UI (imports, direct DB work), clear with `bin/magento configbox:cache:clear`
  — or simply flush the Magento cache: **`bin/magento cache:flush` / `cache:clean` and the admin's
  Cache Management buttons clear the CBX caches too** (the module observes Magento's
  cache-flush events; CLI clears reach web APCu via a shared cache-generation stamp).

All the cache-clearing paths converge on the same cache:

```mermaid
flowchart TD
    A["Normal edits in the CBX admin"] -->|"invalidate automatically"| CACHE[("CBX structure cache<br>APCu or file")]
    B["bin/magento configbox:cache:clear<br>after imports / direct DB work"] --> CACHE
    C["bin/magento cache:flush / cache:clean<br>or the admin's Cache Management buttons"] -->|"module observes<br>cache-flush events"| CACHE
```

## 7. Reading map — the general docs from a Magento seat

| Doc | On Magento 2 |
|---|---|
| [Admin Guide](https://docs.configbox.at/docs/admin-guide/) | **The admin-facing manual** — its [Magento 2 section](https://docs.configbox.at/docs/admin-guide/magento2/) says which of its systems apply here. Point store admins there first. |
| [Configurator building](https://docs.configbox.at/docs/functional/configurator_building) | **Fully applies** — the deep functional reference behind the Admin Guide's product articles. |
| [Rule authoring](https://docs.configbox.at/docs/functional/rule_authoring) / [Calculation authoring](https://docs.configbox.at/docs/functional/calculation_authoring) | **Fully apply.** |
| [Configuration & settings](https://docs.configbox.at/docs/functional/configuration) | Applies to the sections your Settings screen shows; commerce/checkout sections are hidden on Magento (§3). |
| [Commerce setup](https://docs.configbox.at/docs/functional/commerce_setup) | **Not used** — currencies, tax, geography, shipping, payment are Magento's (§1). |
| [Operations](https://docs.configbox.at/docs/functional/operations) | **Mostly not used** — orders/customers/reviews/notifications are Magento's. The Dashboard and License sections still apply. |
| [Frontend user stories](https://docs.configbox.at/docs/functional/user_stories) | The browse/configure epics apply; cart, checkout, orders, account and reviews happen in Magento. |
| [CLI commands](https://docs.configbox.at/docs/technical/cli_commands) | **Fully applies**, via `bin/magento`. |

## 8. Gotchas

- **Don't search Stores > Configuration for CBX settings** — there are none; use
  Configbox > Administration > Settings.
- **Don't expect CBX to send any email on Magento.** If a mail-dependent CBX
  feature from another platform is mentioned in the docs, it does not fire here.
- **Run `bin/magento setup:upgrade` after every CBX composer update** — skipping it
  leaves CBX's database migrations unapplied (a failed migration blocks further
  updates until `configbox:migrate:unblock`).
- **A staging copy under a different hostname needs its own license whitelisting** —
  domain-bound licensing (§2) otherwise degrades rules/features there.
- **Template/asset customizations** belong in the optional companion module
  `Rovexo_ConfigboxCustomizations`, not in the module or library themselves — see the
  [customization overview](https://docs.configbox.at/docs/customization/customization_overview).