# CBX Documentation — full text, version 3.x (released) Generated from the CBX component's own documentation. Canonical site: https://docs.configbox.at/docs/ --- # CBX Admin Guide Page: https://docs.configbox.at/docs/admin-guide/ > **Audience:** store owners, shop managers and back-office staff · **Scope:** setting up and running a CBX store day to day · **Last reviewed:** 2026-07-21 **TL;DR** — Plain-language, step-by-step help for building and running your CBX store: creating configurable products, pricing them, adding conditional logic, setting up commerce (customers, taxes, shipping, payment), and processing orders. **No developer detail** — screens, buttons, fields and outcomes only. Pick a system below, then a task. ## What CBX is (the big picture) CBX turns your website into a store for **configurable products** — products your customers compose step by step (size, material, color, extras …) with a live price and, if you want, a live 2D or 3D preview. Around that configurator sits a complete e-commerce flow: cart, checkout, quotations, invoices, order processing and transactional emails. Everything you manage lives in one place — the **CBX menu** of your site's admin area. The work splits naturally into three phases, and this guide is organised the same way: 1. **Build** — create products, their configuration steps, questions and answers; add rules and pricing; wire up the visual preview. 2. **Set up commerce** — decide who your customers are (groups, B2B/B2C), what they pay (currencies, taxes, discounts) and how orders reach them (shipping, payment). 3. **Operate** — process orders, send the right emails, manage customers, moderate reviews and keep an eye on the dashboard. ## Which platform are you on? CBX runs inside **Joomla**, **WordPress** or **Magento 2**. The CBX screens are the same everywhere, and on Joomla and WordPress this whole guide applies as written. **On Magento 2, read [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/) first.** There, Magento itself is the shop — cart, checkout, orders, customers, emails, taxes, shipping and payment — and CBX provides the configurator. Phases 2 and 3 above happen in Magento, and that page tells you exactly which systems of this guide apply to you. **On Joomla and WordPress**, CBX is the whole shop and every system below applies. One article each covers where the menu lives and how your storefront pages get built: [CBX on Joomla](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-joomla) · [CBX on WordPress](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-wordpress). ## Systems - **[Getting started](https://docs.configbox.at/docs/admin-guide/getting-started/)** — log in, find the CBX menu, learn the shared list & edit screens, run the first-run wizard, and read the dashboard. **Read this first.** - **[Products & configurator](https://docs.configbox.at/docs/admin-guide/products/)** — the heart of CBX: how a configurable product fits together (Product → Pages → Questions → Answers), and how to build one — including images, the visual preview, detail panes and product lists. - **[Rules — conditional logic](https://docs.configbox.at/docs/admin-guide/rules/)** — make the configurator dynamic: show, hide or grey out questions and answers depending on what the customer picks. - **[Pricing & calculations](https://docs.configbox.at/docs/admin-guide/pricing/)** — where prices come from, and the three ways to compute them: visual formulas, code expressions and lookup matrices. - **[Customers, taxes, shipping & payment](https://docs.configbox.at/docs/admin-guide/commerce/)** — customer groups (B2B/B2C, volume discounts), currencies, place-based taxes, shipping methods and payment methods. - **[Orders & daily operations](https://docs.configbox.at/docs/admin-guide/orders/)** — the order lifecycle, invoices and manufacturing slips, status-triggered emails, customer records and review moderation. - **[AI product assistant](https://docs.configbox.at/docs/admin-guide/ai-assistant/)** — the chat advisor on your configurator pages: what it is, setting it up, reading the conversation journal, and working the wishlist of what visitors asked for and it could not do. - **[Store settings](https://docs.configbox.at/docs/admin-guide/settings/)** — the global Settings screen, your store information (used on invoices and emails), the customer-fields matrix and languages. - **[CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/)** — for Magento-hosted stores: who does what, why your CBX menu is shorter, which systems above apply, and how to connect CBX to a Magento catalog product. ## Status The guide is **under construction** — systems are published as they are written. Current state: | System | State | |---|---| | Getting started | ✅ written | | Products & configurator | ✅ written, incl. detail panes, copy/retire and storefront editing | | Rules — conditional logic | ✅ written, incl. recipes | | Pricing & calculations | ✅ written, incl. matrix and code deep-dives, recurring pricing and weight | | Customers, taxes, shipping & payment | ✅ written | | Orders & daily operations | ✅ written, incl. the quotation and saved-cart flows | | AI product assistant | ✅ written, incl. the journal, the insights report and the wishlist | | Store settings | ✅ written, incl. a tour of all 15 Settings sections | | CBX on Magento 2 | ✅ written | Where a system's landing page still lists a *Planned* topic, it means "not written yet", never "nothing to say" — so you can see what's coming. ## What's new Been running a store for a while and want to know what has changed? **[Latest features → the admin](https://docs.configbox.at/docs/features/latest/admin-experience)** covers the backend — dark mode, the on-screen help, the API-token, product-transfer and payment screens, and the assistant's journal — and [Latest features](https://docs.configbox.at/docs/features/latest/) is the whole what's-new track, one article per surface. --- > **Writing or updating articles?** Follow the authoring standard in > `docs/admin-guide/_authoring-standard.md` — task-titled articles, plain language, verified > screen labels, screenshots co-located in each system's `img/` folder. --- # Authoring standard for the Admin Guide Reference section embedded in https://docs.configbox.at/docs/admin-guide/ (no page of its own). > **Audience:** whoever writes or updates `docs/admin-guide/` · **Scope:** how these articles are > written and organised · **Last reviewed:** 2026-07-25 > > This file's leading underscore keeps it out of the Docusaurus sidebar. It is a living standard — > amend it as the guide grows. **TL;DR** — The Admin Guide is for the people who **run a CBX store** — not developers. Every article is a plain-language, task-titled how-to or walkthrough about **screens, buttons, fields and outcomes**. No code, file paths, class names, SQL or architecture. Organised by system (one folder = one Docusaurus sidebar category), with screenshots co-located per system. ## Who it's for — and what it is not - **For:** store owners, shop managers, back-office staff — building products, setting prices, processing orders, changing settings. They know their *store*, not the code. - **Not for:** developers integrating or customizing CBX — that's `docs/technical/` and `docs/customization/`. The functional specs in `docs/functional/` are this guide's *source material*, not its audience-facing counterpart. - **The litmus test:** if a sentence needs a file path, class name, DB column or "the controller/model" to be true, it belongs in the developer docs, not here. ## Where the guide appears — Docusaurus AND the in-admin Help These files are not only Docusaurus source. **Every installation renders them live as its on-screen help**: the guide ships in the release package, and the backend's Help area (**Help** in the CBX menu, plus the per-screen help drawer) reads `docs/admin-guide/` straight from disk at request time — folder structure, `_category_.json` and front matter build the navigation, home cards and search; the articles render through the component's own Markdown renderer (`ConfigboxHelpHelper`, `helpers/help.php`). No build step: what is in the folder on an installation *is* its help content. That gives the front matter and structure jobs beyond the sidebar: - **Stick to the established construct set** — it is also exactly what the in-admin renderer supports: `#`/`##`/`###` headings, paragraphs, `-` and `1.` lists (nested lists, images and tables inside items are fine, blank lines between items are fine), pipe tables, `>` quotes, fenced code, `![alt](img/….jpeg)` images, `**bold**`/`*italic*`/`` `code` ``, and relative `.md` links. **No inline HTML, no reference-style links, no footnotes** — Docusaurus would accept them; the admin renderer intentionally does not. - **Front matter is load-bearing:** `description` appears on the guide home's system cards and in search results; `sidebar_label` is the nav entry; `sidebar_position` orders the nav *and* the previous/next footer. - **`##` headings feed the "On this page" rail and the search index** — keep them short and meaningful. - The `> **Audience:** … · **Scope:** … · **Last reviewed:** …` quote directly under the H1 renders as the article's meta strip — keep exactly that position and pattern. - **Numbered lists render as the step rail** (circled numbers) — use them for real sequences only, which is the rule anyway. - **Keep links and image paths relative.** Relative `.md` links become in-admin navigation; images resolve against the article's folder. - **Documented a screen for the first time?** Map it in `ConfigboxHelpHelper::getScreenArticleMap()` (`helpers/help.php`) so that screen's help drawer opens your article — one line. - **Screen notes live in `_screens/`.** Every backend list and form has a short note at `_screens/.md` — front matter `title` (the screen's name) and optional `article` (the guide article that goes deeper), then two or three sentences and the field list. The help drawer shows the note first and the article beneath it. The underscore keeps these out of the published guide: they are screen reference, not task articles. **A new backend screen needs a note; a renamed field should be fixed in its note as well as in the article.** - **Installations may extend all of this.** The customization layer can append to (or replace) any screen note, add articles in a `Customizations` section, and shadow a shipped article by path — see `customization/com_configbox_help_customization.md`. Two consequences when writing here: a note you write may be **followed by an installation's own additions**, so keep it about the shipped screen and do not close with "that's everything"; and an article you improve may be **shadowed** on some installs, which is a reason to fix a shipped article rather than leave customers to replace it. - **Check your article in the backend Help area too**, not only in Docusaurus — it is the rendering most readers will actually see. ## Structure ``` admin-guide/ README.md ← landing page: big picture + system list + status _authoring-standard.md ← this file (underscore = not in the sidebar) _screens/ .md ← one short note per backend list/form, for the help drawer / _category_.json ← sidebar label + position README.md ← the system's landing page: orientation + task list .md ← one task = one article, kebab-case filename img/ ← screenshots for this system's articles ``` - **Article titles are tasks in the admin's words** — "Add a product", not "The product form". - One article = one job. Split sprawling ones. ## The shape of an article ```markdown --- sidebar_position: N sidebar_label: description: --- # > **Audience:** store admins · **Scope:** · **Last reviewed:** YYYY-MM-DD **What this does** — the outcome in one or two plain sentences. ## Before you start ← access needed / where to be / what to decide ## Steps ← numbered, UI-anchored, with screenshots ## What happens next ← the effect, in plain terms ## Good to know ← the things people forget ## Troubleshooting ← optional: "if you don't see X …" ``` ## Writing rules - **Second person, plain language, short steps.** "You", "click", "enter". Define an unavoidable term in one line, in place. - **Name the exact on-screen labels** — verify them against the live admin (or a current screenshot), never from memory or old docs. Menu paths in bold: **CBX → Products**. - **Use the current (CB4) vocabulary**: Product → **Pages** → **Questions** → **Answers**. Do not use the retired "element", "option" or "option assignment" terms — if an older screenshot or source doc uses them, translate. An answer's library/assignment split no longer exists: an answer belongs to exactly one question. - **Platform-neutral where possible.** CBX runs inside Joomla, WordPress and Magento; write "your site's admin area" and "the CBX menu" rather than host-specific paths. Where a step is host-specific, say so in one line; where a host has more to say than a line (login, menu location, embedding), give it one article in `getting-started/platform/` (pattern: `getting-started/platform/cbx-on-wordpress.md`) and link it from the one-liners. A host that changes **which whole systems apply** — Magento 2, where the host owns commerce — gets its own sidebar system instead (pattern: `magento2/`), and the affected systems carry one prominent platform note each. Screenshots come from the Joomla-hosted demo store — except in a host article, whose screenshots come from that host's dev store, captured at the same settings. The CBX screens themselves are the same on every host. - **Screenshots:** co-locate in the system's `img/` folder and reference relatively, always with meaningful alt text: ```markdown ![The Products screen](img/products-list.jpeg) ``` Capture with the repo's capture script (see below) so they are consistent (same demo data, same window size, light theme). Retake the affected screenshots whenever a screen changes visibly. - **Link only within the Admin Guide.** If a developer note is unavoidable, one line at the very bottom: ``For developers → `docs/technical/.md` `` — a backticked path, **not** a link (the Admin Guide is intended as its own Docusaurus instance; cross-instance `.md` links break the build). - **Docusaurus conventions:** kebab-case filenames; folder = category with `README.md` + `_category_.json`; `description` front matter on every article; relative `.md` links; wrap `` and `{braces}` in backticks so MDX doesn't eat them. ## Screenshots — the capture script Screenshots are captured, not hand-made: `tests/tools/capture-admin-guide.mjs` (in the Joomla dev repo, next to the E2E suite) logs into the dev store's admin and captures every screen the guide references at a fixed size, writing straight into the `img/` folders here. Add new screens to its target list; re-run after UI changes. Hand-cropped detail shots are fine as a supplement, but the full-screen baselines come from the script. Host-article screenshots come from that host's dev repo at the same settings — WordPress: `tools/capture-admin-guide.mjs` in `cbx-wordpress`. Anything sensitive a screen shows (the license key) is blurred in-page by the scripts, never hand-edited — keep it that way when adding targets. The `magento2/` system's shots come from the equivalent script in the Magento dev repo instead, because they show the Magento backend and storefront. Same size, format and rules. In `cbx-magento`, run it from the E2E suite: ``` cd tests/e2e && npm run capture-admin-guide # all targets cd tests/e2e && npm run capture-admin-guide -- cart # one target ``` It lives at `tests/e2e/tools/capture-admin-guide-m2.mjs` — next to the suite rather than in the repo's top-level `tools/`, because that is the only place Node resolves `@playwright/test` from. It reads `MAGENTO_ADMIN_URL/_USER/_PASS` and `MAGENTO_SITE_URL` from `.claude/secrets/credentials.env`, and blurs the license key **and the licence holder's domain names** in-page. (The retired `configbox_magento2` harness carried the original version of this script; that copy is dead once the harness goes.) ## Checklist — an article is done when … - [ ] The title is a **task** in the admin's words. - [ ] No code, paths, class names, SQL or architecture — screens, fields and outcomes only. - [ ] Steps name the **exact, verified** on-screen labels and menu paths. - [ ] CB4 vocabulary throughout (pages / questions / answers). - [ ] At least one screenshot per major screen touched, captured via the script. - [ ] "What this does" / "What happens next" state the effect plainly. - [ ] Filed under the right system; the system `README.md` links to it; front matter present. - [ ] If it documents a screen, that screen's `_screens/.md` note is present and its field names agree with the article. - [ ] Renders cleanly in the **backend Help area** (construct set respected — no inline HTML, no reference links); if it documents a screen, that screen is mapped in `ConfigboxHelpHelper::getScreenArticleMap()`. --- # Addresses Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/manage-customers (no page of its own). Addresses in the Commerce 2 system, held per customer rather than per order — so one customer can keep several and documents point at them. - **Customer** — the party this address belongs to. - **Label** — a name you recognize it by, e.g. "HQ" or "Warehouse 2". - **Recipient name** and **Address line 1 / 2** — the postal block. - **State / Province / Region** — the ISO subdivision code; required for US and Canadian tax. - **Tax ID** — the ship-to VAT number; authoritative for tax determination. --- # Answers Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/add-answers (no page of its own). The selectable options of a choice question — each with its own price, image and availability. An answer belongs to exactly one question. - **Title** — per language; what the customer reads. - **Price** — what this answer adds to the product price. - **SKU** — the answer's article number, shown on order line items. - **Weight** — what it adds to cart weight, for weight-based shipping. - **Default** — preselect this answer. - **Picker Image** / **Visualization Image** — the image in clickable-image questions, and the overlay used by the composite-image preview. Overlays accept **JPG and PNG only** (the product's base image also takes GIF/TIF/BMP), and want PNG for transparency. - **Visualization Stacking Order** — where this overlay sits in the stack; **higher is nearer the front**. Give each layer its own number rather than sharing one. - **Available** and **Availability date** — switch an answer off, or schedule it. --- # API Tokens Reference section embedded in https://docs.configbox.at/docs/admin-guide/settings/manage-api-tokens (no page of its own). The access tokens external software and AI assistants present to use the store's API. Creating one reveals it a single time — copy it then, because only a fingerprint is kept. Revoking is permanent and takes effect on the caller's next request. - **Name** — free text naming the holder, so the right token can be picked out when it is time to revoke one. - **Scopes** — a grid of the store's seven **areas** (catalog, store, customers, orders, conversations, code, system), each with a **read** and a **write** box. Write includes read; rows are independent of each other; the store row's read box is "always" because every token reads store configuration. The **Start from** buttons tick the boxes for a common job — none of them ticks **code**, which lets a caller put program code on the server and is only ever granted by hand. - **Expires** — the token stops working at the start of this day; empty means it never expires. - **Revoked** — one-way switch that shuts the token off for good. - **Created / Last used** — when it was made and when it last authenticated a request; a token unused for months is a retirement candidate. --- # Code Calculations Reference section embedded in https://docs.configbox.at/docs/admin-guide/pricing/write-a-code-expression (no page of its own). A typed expression, for math that is quicker to write than to drag: percentages of the running total, area and volume formulas. Bind up to four questions to the placeholders **A**, **B**, **C** and **D**, then write the expression in the **Code** box. Three rules break most expressions: a dot is the decimal mark, no thousands separators, and a space before and after every placeholder and keyword. There is no preview — always check a code calculation live in the configurator. --- # Formula Calculations Reference section embedded in https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation (no page of its own). The visual calculation editor: build the arithmetic by dragging terms in rather than typing an expression. Terms come from the **Condition Types** tabs — question entries and selections, results of other calculations, customer-group values, and the **Round** / **Lowest value** / **Highest value** functions. Best for per-question, per-dimension math you want to read back at a glance. Compose several small named calculations rather than inflating one. --- # Matrix Calculations Reference section embedded in https://docs.configbox.at/docs/admin-guide/pricing/price-with-a-matrix (no page of its own). A lookup table: pick what the rows and columns key on, fill the grid, and the customer's choices read a value out of it. This is the honest option when your pricing is a printed table. Each axis is a **question** (its entered value or its selected answer), the **result of another calculation**, or ignored — a matrix with one axis ignored is a simple one-dimensional lookup. The axis label tells you what CBX will read. You cannot mix the two within one axis. --- # Calculations Reference section embedded in https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation (no page of its own). Named formulas belonging to a product, used wherever a number has to be worked out rather than typed: a price that depends on entered dimensions, a weight, a quantity-dependent surcharge. Every calculation has a **style**, and the style decides the editor you get: - **Formula** — the visual editor: drag in question entries, other calculations, customer values and functions (**Round**, **Lowest value**, **Highest value**). - **Code** — a typed expression, better for totals-based math. - **Matrix** — a lookup table, when pricing genuinely *is* a table. A calculation does nothing until it is attached — as a question's or answer's **Price Calculation**, as a minimum or maximum, or referenced from a rule or another calculation. --- # Character Set Repair Reference section embedded in https://docs.configbox.at/docs/admin-guide/ (no page of its own). A maintenance job, not a daily screen: it converts CBX's database tables to the character set current versions expect. Older installations can carry tables from an earlier standard, which shows up as mangled accented characters and emoji in titles and descriptions. The screen reports how many tables still need converting and works through them one at a time, so a large database does not time out. It is safe to re-run and safe to stop — converted tables stay converted. **Back your database up first**, and run it when the store is quiet. --- # Conversation Journal Reference section embedded in https://docs.configbox.at/docs/admin-guide/ai-assistant/read-the-conversation-journal (no page of its own). Every conversation visitors have with the AI assistant, with what happened in it: selections made, whether the cart was reached, refusals, wishlist items and errors — filter by any of them, or search the transcripts. Each conversation gets an AI-written **lessons-learned review**, and old conversations are deleted after the retention period from the settings. Both happen through a **scheduled script on the server** — if reviews stop appearing on their own, that schedule is the thing to check. --- # Conversation Insights Reference section embedded in https://docs.configbox.at/docs/admin-guide/ai-assistant/run-the-insights-report (no page of its own). The observatory over the assistant's conversations: how much is waiting for each group on the Recommendations screen, how the picture moved in the last 30 days (including what is assigned to you), and — below the digest — **what visitors asked for and did not get**, live and in their own words. The demand ledger needs no analysis run: the assistant files these the moment a visitor asks for something it cannot serve, so the list is current as of the last conversation. A line saying "asked 5x" is five real visitors, each quote one click away. The curated, deduplicated versions of the same signals land on the Recommendations screen once conversations are analysed by the **scheduled script on the server**. --- # Cities Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes (no page of its own). City-level entries, the most specific step of the tax chain and the first one checked. Create one only where a city's rate genuinely differs from its county, state or country; everything else inherits automatically. --- # Settings Reference section embedded in https://docs.configbox.at/docs/admin-guide/settings/tour-the-settings-sections (no page of its own). The store-wide defaults, grouped into collapsible sections: languages, checkout, invoicing, reviews, the configurator's behaviour, storefront block headings, the live selection overview, geolocation, the licence key, the custom-field labels used on products, questions and answers, maintenance, connectors, structured data and analytics, the asset and debugging switches, and the AI configurator assistant. Anything set here is the default; many settings can be overridden per product. Several sections embed a manager for related records — currencies, tax classes, salutations — so you can set them up without leaving the screen. --- # Connectors Reference section embedded in https://docs.configbox.at/docs/admin-guide/ (no page of its own). Custom integration files that run alongside CBX — the seam a developer uses to connect your store to another system (an ERP, a stock feed, a bespoke export). Reached from **Settings**. - **Name** — what the connector is for. - **Connector File** — the file that implements it. - **Execute after system connectors** — whether it runs after CBX's own, so it can build on their result. - **Ordering** and **Active** — the order connectors run in, and whether this one runs at all. Entries here are set up by whoever wrote the integration; if you did not add one, leave the screen alone. --- # Counties Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes (no page of its own). The level between state and city, for tax regimes that charge at county level (US sales tax, typically). A county is only worth creating when it carries a **Tax Override** — otherwise the state or country rate already covers it. --- # Countries Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes (no page of its own). The countries you sell to, and everything place-dependent about them. - **Active** — whether the country can be chosen at checkout. - **Tax Override** — this country's rate for any tax class; leave empty to inherit the class's default. - **VAT free** / **In EU VAT Area** — the two flags that override the rate chain: no VAT for this country, and EU B2B reverse-charge handling. - **Zones** — which shipping zones the country belongs to. --- # Currencies Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/manage-currencies (no page of its own). Every currency your store can display, and what one unit of it is worth against your **base currency**. Reached from **Settings**, where it sits as an embedded manager. - **Title** — the currency's name, per language. - **Currency Code** — the three-letter ISO code (`EUR`, `USD`), used by payment providers. - **Currency Symbol** and **Multiplicator** — what customers see, and the conversion rate applied to every price authored in the base currency. - **Base Currency** — the currency you author prices in. Change it only before you have orders. - **Default** — the currency a visitor sees first. - **Active** — whether customers can switch to it at all. --- # Customer Groups Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-customer-groups (no page of its own). Your customer segments — retail, trade, wholesale. A group decides how prices are shown, what a customer may do, and what volume discount they get. Reached from **Settings**. - **Name** — back-office only. - **Platform Group** — the site user group that maps here; a logged-in customer's group follows from this. - **Tax display mode** — **B2C** (tax-inclusive prices) or **B2B** (net prices, tax added). - **Enable price display in configurator and cart** — off for a browse-only or quote-only group. - **Enable checkout**, **Enable Save Order**, **Enable Quotation Request** — what the group may actually do. - **Discount Levels** — up to five bands, each with a net order total to start at, a discount type, and the amount or percentage. --- # Customers Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/manage-customers (no page of its own). The people who ordered — their addresses, their group, and the settings that decide how they are taxed and what they are shown. - **Billing Address** and **Delivery Address** — company, salutation, name, address, country and state, email, phone; delivery collapses when it is the same as billing. - **VAT IN** — the VAT number; for EU B2B customers this drives reverse-charge handling. - **Customer group** — moves the customer between segments and so changes their pricing mode and permissions. - **Language** and **Newsletter** — communication preferences. - **Platform User ID** — the linked site account; this is how a login lands on this record. --- # Dashboard Reference section embedded in https://docs.configbox.at/docs/admin-guide/getting-started/check-the-dashboard (no page of its own). The store's front page: what has been happening, and what needs your attention. Critical issues and health checks sit alongside the store's key figures, recent orders, catalog counts and your licence status. Read it as a morning check — anything flagged red is worth resolving before it affects customers. --- # Examples Reference section embedded in https://docs.configbox.at/docs/admin-guide/ (no page of its own). Example records used by the rule and calculation editors to demonstrate what a condition or term does. They are not part of your catalog and never appear on the storefront. - **Title** — the example's name in the editor. - **Product** — the product it illustrates. - **Description** — the explanatory text shown with it. - **Ordering** and **Active** — where it appears in the list, and whether it appears at all. --- # Licence Reference section embedded in https://docs.configbox.at/docs/admin-guide/getting-started/check-the-dashboard (no page of its own). Your CBX licence key and what it entitles this installation to — the domains it covers and until when updates are included. Enter the key you received with your purchase. The dashboard shows the resulting status; if updates stop arriving, this is the first screen to check. --- # Product Lists Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/manage-product-lists (no page of its own). Your catalogs — the pages that show several products. A product can appear in any number of lists; a product in no list is only reachable by direct link. - **Title** and **Description** — per language; the list's name and the text above it. - **Template** — the layout that renders the list. - **Sort products by** — **Title** (alphabetical) or manual drag ordering. - **Active** — live or not. --- # Notifications Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/set-up-order-emails (no page of its own). The transactional emails your store sends. One template per order status, each carrying two independent messages: one to the customer, one to the shop manager. - **Name** — the back-office label, e.g. "Payment Confirmation". - **Status Code** — the order status that fires this template. - **E-Mail to Customer** and **E-Mail to Shop Manager** — each with its own **Send email** switch, **Subject** and **Email HTML** body, per language. No email went out? Check that a template exists for that exact status and that the right recipient's **Send email** is on. --- # Orders Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/process-an-order (no page of its own). Every order, quotation and saved cart, newest first. Opening one shows what was configured, who ordered it, what was charged — and the status control that drives the whole lifecycle. - **Ordered Products** — each position with quantity and price; **Details** unfolds the full configuration the customer chose. - **Status** — changing it is the main action here; it can fire the customer notification for that status. - **Invoice** — download or generate the invoice, depending on your invoicing mode. - **Manufacturing Slip → Download** — the production and packing PDF for the workshop. Quotations and saved carts live in this same list under their own statuses. --- # Manufacturing Slip Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/process-an-order (no page of its own). The production and packing PDF for one order — every position with its full configuration, written for the workshop rather than the customer. It is generated on demand from the order, not stored, so it always reflects the order as it stands now. You reach it from an order's **Manufacturing Slip → Download**. --- # Pages Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions (no page of its own). A page is one step of a product's configurator — the tabs or sections a customer moves through. Pages hold the questions. - **Title** — per language; the step's tab label. - **Description** — optional intro text shown on the step. - **Ordering** — the sequence customers walk through. - **Active** — whether the step is part of the configurator at all. --- # Payment Methods Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-payment-methods (no page of its own). What the customer can pay with, and what each option costs them. - **Title** — per language; what checkout shows, e.g. "Bank transfer". - **Payment provider** — who handles the money. Its settings appear right below the choice; the status note under them says whether the provider is ready. A method whose provider is not ready is never offered at checkout. - Provider credentials are stored encrypted — a saved key shows "a value is stored"; blank keeps it, typing replaces it. - **Static extra charge** and **Extra charge percentage** — a surcharge for this method. - **Available for these customer groups** / **for these countries** — restrict who is offered it. The country list is collapsed behind a counter; use the filter box to find entries fast. - **Active** — offered or not. Test every provider's full round trip in its test mode before going live. --- # Payment Providers Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-payment-methods (no page of its own). The Commerce 2 registry of payment connectors — the integrations available to payment methods, and the credentials each one needs. - **Provider** — which integration this entry configures. - **Title** — how it is referred to in the back office. - **Published** — whether it can be used at all. - **Test mode** — run against the provider's sandbox instead of live. - **Settings** — the provider's own credentials and options. Configure a provider here once, then reference it from the payment methods customers see at checkout. Always complete a full round trip in test mode before going live. --- # Payments Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/track-payments (no page of its own). Every payment attempt customers make, whatever its fate — paid, declined, pending, abandoned. - Filter by state, provider, test/live or date; an order retried by the customer shows one row per attempt. - Click a row for the payment's full story: amounts, provider references, and the timeline of everything that happened. - **Mark as settled** — confirm money that arrived outside the provider (bank transfers). - **Mark as failed** — write off a dead attempt. - **Check with provider** — fetch the current status immediately (pending payments are also re-checked automatically). - **Recent events** lists the latest provider calls across all payments. --- # Setup Wizard Reference section embedded in https://docs.configbox.at/docs/admin-guide/getting-started/run-the-setup-wizard (no page of its own). The first-run assistant: licence key, store identity, your company's country and tax mode (B2C or B2B), base currency and languages. It appears once, on a fresh installation, and then never again — everything it asks for stays editable in the normal screens afterwards, so nothing you enter here is locked in. --- # Product Detail Panes Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/product-detail-panes (no page of its own). Reusable content blocks (accordions or tabs) on a product's detail page — delivery terms, material notes, care instructions. Written once, attached to as many products as you like. - **Heading** — per language, required; the pane's title on the storefront. - **Heading Icon** — optional small symbol beside the heading. - **Content** — the body, per language, in a full HTML editor. - **CSS Classes** — optional styling hooks for a web developer. --- # Product List Assignments Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/manage-product-lists (no page of its own). Which products sit in which list, and in what order. You normally reach this from a product's own form (the product-lists tickboxes) or by dragging products inside a list with manual sorting — this screen is the same relationship seen from the list's side. --- # Products Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/add-a-product (no page of its own). The product tree and the product form. A product is the root record customers configure: its names and URL slugs per language, the lists it appears in, its images, its starting price, and what its detail page, listing tile and configurator look like. - **Title** and **SEF Segment** — per language; the name customers read and the product's URL slug. - **In which product lists do you want to show this product?** — the catalogs that carry it. - **Should the product be displayed?** — the master visibility switch; keep it **No** while building. - **Visualization** — none, **Composite Image** (2D layers) or **ShapeDiver** (3D). Choosing Composite shows the preview frame straight away, so an empty gap beside the questions means the artwork is not uploaded yet. The base image is optional; layers can render over nothing. - **Base price** and tax class — the price before any options are chosen. Its configuration steps live one level down: [pages and questions](https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions). --- # Product Transfer Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/move-products-between-sites (no page of its own). Moves products between CBX installations — typically from a staging or test site to the live one. A transfer file carries the whole product: its configurator pages, questions, answers, prices, calculations, rules and images. The top half exports: filter the list, tick the products you want and download one file. The bottom half imports: choose the file, choose whether the products should be created as new or should replace the originals, and CBX checks the file against this site before writing anything. **Read the check results before confirming.** Replacing products can delete saved configurations from customers' shopping carts, and the check tells you exactly how many. --- # Product Tree Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/how-a-product-fits-together (no page of its own). The catalog's navigation, in the shape the data actually has: **Product → Pages → Questions → Answers**. Expand a product to reach its configuration steps, a page to reach its questions, a question to reach its answers. **Add product** at the bottom creates a product; ticking one and using **Copy** duplicates everything below it — pages, questions, answers, rules and calculations — with all internal references re-pointed to the copy. --- # Questions Reference section embedded in https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions (no page of its own). The inputs on a configurator page — what you ask the customer, and how they answer it. - **Title** — per language; the question text customers see. - **How do you want to display the question?** — the question type: choice types (radio, dropdown, checkbox, clickable images) take **Answers**; value types (text, number, slider, calendar, file upload) take what the customer types or picks. - **Does the question have to be answered?** — makes it required. - **Internal Name** — an admin-only label, invaluable once a product has dozens of questions. - **Show in Overview** — whether it appears in the live price and selection summary. Choice questions still need their [answers](https://docs.configbox.at/docs/admin-guide/products/add-answers); a **Rule** makes the question conditional. --- # Reviews Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/moderate-reviews (no page of its own). Customer product reviews awaiting your decision. Nothing appears on the storefront until you activate it. - **Active** — the approve switch, from the form or straight from the list row. - **Name**, **Rating** and **Comment** — what the customer submitted. - **Product** and **Language** — what it is about, and where it shows. Edit before approving to trim personal data or fix formatting — keep edits light, a review is the customer's words. Delete spam or abuse outright. --- # Rule Editor Reference section embedded in https://docs.configbox.at/docs/admin-guide/rules/build-a-rule (no page of its own). Makes a question or answer conditional: it shows — or hides — only when the conditions you build here are met. Pick the rule's meaning at the top (**Show ... if these conditions are met** or **Hide ...**), then drag conditions in from the **Condition Types** tabs: answers to questions, results of calculations, customer group. Click a condition to set its **operator**, and combine several with the **AND** / **OR** combinators; **Put in parentheses** controls precedence. Save in the editor, then save the question or answer form. --- # Salutations Reference section embedded in https://docs.configbox.at/docs/admin-guide/settings/tailor-the-customer-fields (no page of its own). The options behind the *Salutation* field on address forms — Mr, Ms, and whatever else your market expects. Reached from **Settings** as an embedded manager. - **Title** — per language; what the customer picks from. - **Gender** — what the salutation implies, used where wording has to agree. Whether the field appears at all, and whether it is required, is decided per flow on the Customer Fields screen. --- # Shippers Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-shipping (no page of its own). Your carriers — "DHL", "UPS", "Local courier". These are labels that group shipping methods, so there is nothing to configure beyond the **Title** and whether the shipper is **Active**. Create them first; the shipping methods that customers actually choose reference them. --- # Shipping Methods Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-shipping (no page of its own). One entry per delivery offer the customer can pick at checkout. - **Title** — per language; what checkout shows. - **Shipper** and **Zone** — who carries it, and where it applies. - **Minimum / Maximum Weight** — the cart-weight band this method covers. - **Delivery Time** — a plain "5 days" promise shown to the customer. - **Price** and **Tax Class** — what it costs, and how that cost is taxed. A customer sees no options when their country is in no zone, or the cart weight falls outside every band. --- # Store Information Reference section embedded in https://docs.configbox.at/docs/admin-guide/settings/keep-store-information-current (no page of its own). Who your store legally is. These values print on invoices and quotations and appear in emails, so they are worth keeping current. - **Identity** — shop name, website, and the logo used on PDFs. - **Address & contact** — the address block, sales and support phone and email. - **Banking** — bank name, account holder, IBAN, BIC; printed on invoices for bank transfer. - **Legal/registration** — VAT number, commercial register ID, company owner, legal venue. - **Shop Description** — translatable text usable in templates and communications. Update it the day your address, bank account or contact details change: the next generated invoice uses the new values. --- # States Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes (no page of its own). States and provinces within a country — needed where addresses require them, or where tax differs below country level. Rate lookup runs most specific first: **City → County → State → Country → the class's default rate**, so a state entry here only matters if it carries a **Tax Override** or if your customers must pick a state at checkout. --- # Tax Classes Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes (no page of its own). Named rate buckets — *Standard*, *Reduced* — that products, shipping methods and payment surcharges point at. Each class carries a **Default Tax** rate, used wherever no place-based override applies. One *Standard* class is enough for most stores; add more only if you sell goods at mixed rates. Per-country, per-state, per-county and per-city overrides live on the geography screens. --- # Customer Fields Reference section embedded in https://docs.configbox.at/docs/admin-guide/settings/tailor-the-customer-fields (no page of its own). A matrix: every address and account field down one side, and each flow — **Checkout**, **Quotation**, **Save Order**, **Profile** — across the top. For each combination you choose whether the field is shown, and whether it is required. A B2B store requires *Company* and *VAT IN* at checkout; a consumer store hides both everywhere. Delivery-address fields appear when the customer unticks "same as billing". The Mr/Ms options themselves are managed in the Salutations manager. --- # Shipping Zones Reference section embedded in https://docs.configbox.at/docs/admin-guide/commerce/set-up-shipping (no page of its own). Geographic groupings that shipping prices key on — *Domestic*, *EU*, *Rest of World*. Each zone holds the countries that belong to it; the customer's country selects the zone, and the zone plus the cart weight selects which shipping methods are offered. A country can also be assigned to zones from its own form on the Countries screen. --- # Customers & Contacts Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/manage-customers (no page of its own). The Commerce 2 party record: one entry per customer, which may be a person or an organization. - **Type** — **Person** or **Organization**. - **Name** — the display name. - **Assigned agent** — the sales agent this customer belongs to. - **Default billing address** / **Default shipping address** — which of the party's addresses is used unless a document says otherwise. - **Tax ID** — a registration number kept as a hint; the address is what actually determines tax. - **Details withheld** — set when an agent deliberately withholds a customer's details. People and organizations are linked to each other on the Party Relationships screen. --- # Party Relationships Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/manage-customers (no page of its own). How people and organizations connect: a contact **works at** a company, is a **contact of** it, or an organization is **parent of** another. - **Person** and **Organization** — the two ends of the relationship. - **Relationship** — which kind of link it is. - **Primary** — the main contact for that organization. This is what lets several buyers order under one company account while each keeps their own login and contact details. --- # Quotes Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/quotations-and-saved-carts (no page of its own). Quotes in the Commerce 2 system — a configured cart offered to a customer at agreed terms, before it becomes an order. - **Quote no.** — the reference the customer quotes back. - **Status** — where the quote stands. - **Valid until** — the date the offer lapses. - **Currency**, **Discount %** and **Discount reason** — what was offered, and why it differs from list price. Accepting a quote converts it into an order; the quote itself is frozen at that point, so its figures stay as they were offered. --- # Orders (Commerce 2) Reference section embedded in https://docs.configbox.at/docs/admin-guide/orders/process-an-order (no page of its own). Orders in the Commerce 2 system, alongside the classic Orders screen. - **Order no.** — the customer-facing reference. - **Paid** and **Paid on** — payment state and when it landed. - **Customer** and addresses — who ordered, and where it ships and bills. - **Net total** and totals — frozen at order time, so later price or tax changes never rewrite an existing order. --- # The AI product assistant Page: https://docs.configbox.at/docs/admin-guide/ai-assistant/ > **Audience:** store owners and shop managers · **Scope:** what the assistant is, what it can and > cannot do, and what running it involves · **Last reviewed:** 2026-08-11 The AI product assistant is a chat panel on your configurator pages and on the cart. Visitors ask questions in their own words — and their own language — and the assistant answers from your product data, makes selections for them, and guides them to a finished configuration. It is off until you configure it; see [Set up the assistant](https://docs.configbox.at/docs/admin-guide/ai-assistant/set-up-the-assistant). ## What it knows The assistant is briefed from what your store already contains — it does not invent product facts: - The product's **pages, questions and answers**, with their prices as your store calculates them. - The **descriptions** you write on products, questions and answers. - The product's **detail panes** — this is where it learns specifications, delivery terms, warranty conditions and anything else you put there. A well-filled set of detail panes is the single best way to make the assistant genuinely helpful. - The visitor's **live configuration**: what is selected right now, what a rule currently allows, what is still open, and the running total. When a visitor asks something your data does not answer, the assistant says so honestly — and files the gap on [the wishlist](https://docs.configbox.at/docs/admin-guide/ai-assistant/work-the-wishlist) so your team learns what is missing. ## What it can do - **Explain and advise**: compare options, explain why something is unavailable, answer "what would happen if…" questions without changing anything. - **Configure**: make selections the visitor asks for, respecting every rule your product defines. Selections the rules forbid are refused, never forced. - **Guide the page**: switch configurator pages and point at a question when the visitor asks to be shown something. The visitor sees the page move and the question highlighted. - **Finish the purchase**: put the completed configuration in the cart — only when the visitor clearly asks for it, and only if you allow it in the settings. - **Work the cart**: on the cart page it can change a line's quantity, remove a line, copy one so the visitor can configure a second that differs, or reopen a line for editing — the same things the buttons on the cart page do, and only if you allow it. It reads the basket first, so a visitor with several lines can talk about any of them, not just the one they came from. When a visitor with more than one line says something that fits several of them, the assistant does not pick for them: it puts one button per line on screen and lets them tap the one they meant. ## What it never does - It never sees or invents prices — every figure comes from your store's own calculation. - It never does anything a visitor could not do themselves on the page. It has no access to your administration, your orders, or other visitors' data. - It never confirms a change on the visitor's behalf when a question is set to "let the customer confirm" — the visitor is always asked. - It never pushes to the cart uninvited, and it respects the permissions you set. - It never removes a line without asking first and being told yes in a later message, and the question always names the line it is about to remove — so a visitor with several lookalike rows can see which one is at stake. - It never touches a line that is not in the cart in front of it: not another shopper's, and not one of the same visitor's own older carts. Once a cart has become an order it can only be read. ## What running it involves - **An Anthropic API key** — the assistant is powered by Claude. You pay Anthropic per message, in the range of cents; a rate limit per visitor keeps spend bounded. The key never leaves your server. - **A scheduled script** if you use the conversation journal — it writes the per-conversation reviews and enforces the retention period. See [Schedule the recurring scripts](https://docs.configbox.at/docs/admin-guide/getting-started/schedule-the-recurring-scripts). ## Where you see what it did Every conversation is recorded in the [conversation journal](https://docs.configbox.at/docs/admin-guide/ai-assistant/read-the-conversation-journal): what the visitor asked, what the assistant answered, every selection it made and why it took each action. The [wishlist](https://docs.configbox.at/docs/admin-guide/ai-assistant/work-the-wishlist) collects what your store was missing, [Recommendations](https://docs.configbox.at/docs/admin-guide/ai-assistant/send-recommendations-to-your-team) turns all of it into a living to-do list per team — with a contact and an email per group — and [Conversation Insights](https://docs.configbox.at/docs/admin-guide/ai-assistant/run-the-insights-report) shows how that list is moving. The assistant above works for your visitors. The store can also open a door to an AI assistant that works for **you** — one you already use, given a token that says exactly what it may touch, so it can build products, write texts and rules, or read what visitors asked for. See [Connect your own AI assistant](https://docs.configbox.at/docs/admin-guide/ai-assistant/connect-your-own-ai-assistant). --- # Connect your own AI assistant Page: https://docs.configbox.at/docs/admin-guide/ai-assistant/connect-your-own-ai-assistant > **Audience:** store owners, shop managers and the developers who help them · **Scope:** giving an > AI assistant of your own access to the store, and deciding what it may do · **Last reviewed:** > 2026-08-25 **What this does** — The AI product assistant on your configurator pages talks to *visitors*. This is the other direction: an AI assistant that works for **you** — Claude Code, Claude Desktop, or any tool that speaks the Model Context Protocol — gets a door into the store and a set of tools it can use through it. It can then build and tidy products, write the texts and rules, check on orders, tell you what visitors keep asking for, or keep the installation healthy — whichever of those you allow. ```mermaid flowchart LR YOU["You, in your AI tool"] --> AI["The assistant"] AI -- "one address + one token" --> STORE["Your store"] STORE --> T1["reads products, pages,\nquestions, answers, prices"] STORE --> T2["creates and changes them\n— if the token allows"] STORE --> T3["checks orders, customers,\nconversations — if allowed"] ``` The assistant never sees your database directly and never bypasses the store's own checks: every change it makes goes through the same validation a person saving a form goes through, and it can only reach the areas its token was given. ## What you need - A store on a web address the assistant's computer can reach. For an assistant running on the same server as the store, a developer can connect it locally instead. - An **API token** for the assistant — see [Manage API tokens](https://docs.configbox.at/docs/admin-guide/settings/manage-api-tokens). The token is what decides what the assistant may touch, so choose it deliberately (next section). - An AI tool that can connect to an MCP server over the web, with a bearer token. Claude Code does; so do a growing number of desktop assistants and editors. Its own documentation says where to paste an address and a token. ## Give it exactly the access the job needs Open **API Tokens** in the CBX menu, click **Add**, name the token after the assistant, and use a **Start from** button: - **author** — the assistant builds and maintains your catalog: products, pages, questions, answers, texts, rules and prices. It cannot see a single customer or order. This is the one to start with. - **insights** — the assistant reads your catalog and the visitor conversations, and tells you what people ask that your store does not answer. It changes nothing. - **fulfilment** — the assistant works orders and can see who they belong to; nothing else. - **operator** — store configuration and installation housekeeping; no customer or catalog access. Then adjust the boxes if the job is different, and save. **Copy the token from the screen right away** — it is shown once. Two boxes deserve a moment's thought before you tick them: - **customers** and **orders** are personal data. Give an assistant those rows only when its job is about customers or orders, and prefer *read* unless it really has to change them. - **code** lets the assistant write price calculations as program code — which is program code running on your server. No Start-from button ticks it. Tick it yourself, only for an assistant a developer is supervising, and untick it again when that work is done. An expiry date is a good habit for an assistant used for one project: the access ends by itself. ## Connect it Every assistant asks for the same two things: - **The address**: your store's web address followed by `/cb-api/v1/mcp` — for example `https://www.example.com/cb-api/v1/mcp`. - **The token**, sent as a bearer credential. Most tools have a field for it; in Claude Code a developer adds the store with one command, passing the address and the token. Once connected, the assistant sees a list of tools — only the ones its token allows — and starts by asking the store to describe itself: which entities exist, which fields they have, which languages the store runs, and what this store has been customized with. You do not have to explain any of that; it learns it from the store. ## What it can do, and what it asks first With an **author** token the assistant can create a product from a brief, add its pages, questions and answers in every language your store runs, write the detail texts the visitor-facing assistant later answers from, set up rules and price calculations, and check its work by reading it back. With **insights** it can read every conversation the visitor-facing assistant had and tell you which questions went unanswered. Some tools are marked as **destructive** — deleting a product and everything under it, importing a product package, running database housekeeping. An assistant that respects those marks will ask you before using one. The store enforces the token regardless: a tool the token does not allow is refused even if the assistant tries it by name, and the refusal says which permission was missing. ## Keep an eye on it - **API Tokens** shows when each token was last used. An assistant token that has gone quiet can be revoked. - Every tool the assistant uses is recorded in the store's authorization log with the token's name — a developer can show you the trail. - If a token leaks, revoke it and mint a new one; the assistant reconnects with the replacement. ## Good to know - The same token works for the store's ordinary API too — one credential, one meaning. - The assistant's changes land immediately and there is no undo, exactly as if a person had saved the form. Start it on a staging copy of the store if you want to see how it works first. - Nothing here affects the visitor-facing AI product assistant; the two are configured separately and can run together. --- # Read the conversation journal Page: https://docs.configbox.at/docs/admin-guide/ai-assistant/read-the-conversation-journal > **Audience:** store owners, shop managers and whoever improves the store · **Scope:** the > Conversation Journal screens and how to read them · **Last reviewed:** 2026-08-11 **AI Assistant → Conversation Journal** lists every conversation visitors had with the assistant. Because it shows visitors' words verbatim, only the platform's highest privilege sees it — on Joomla that is Super Users. ## The list ![The conversation journal](./img/journal.jpeg) Each conversation is one row with a public reference (like CADV-ABC123) that other reports can point at. The **signal chips** tell you at a glance what happened: - **Selections** — how many configuration changes the assistant made. - **cart** — the configuration reached the cart. - **refused** — selection attempts the rules rejected. - **wish** — items the assistant filed on [the wishlist](https://docs.configbox.at/docs/admin-guide/ai-assistant/work-the-wishlist). - **unfulfilled** — wishes that a concrete visitor request triggered: someone asked for something in vain. The strongest demand signal in the journal. - **error** — turns that failed technically. - **Tone** — the visitor's mood as judged from their wording, once the conversation is analyzed. Filter by any signal, by product, or search the transcripts. The stat cards above the list sum the same signals over everything. ## One conversation ![One conversation: signals and the full timeline](./img/conversation.jpeg) The detail page shows the full timeline, top to bottom, exactly as it happened: - **Bubbles** — the visitor's messages and the assistant's replies. - **Reasoning lines** — the assistant's own one-sentence rationale before each action. Visitors never see these; they exist for you. - **Tool chips** — every action with its outcome, color-coded: green selections, red refusals, amber "needs confirmation", blue lookups. - **Page and cart actions** — when the assistant switched the visitor's page, pointed at a question, added to the cart, or worked the basket — changed a quantity, removed a line, copied one, reopened one for editing, or asked which line was meant — the row names the action, its category and the assistant's stated reason for taking it right then. A removal shows twice: once where the assistant asked, and once where the visitor's yes let it through. - **Wishlist items** — collapsed to their category and title; expand for the details and the visitor's original words. - **Selections changed in this turn** — a before/after comparison of the whole configuration, expandable per turn. ## The lessons review Each conversation gets one AI-written review: what the visitor wanted and whether they got it, what worked, what went wrong, and every gap judged for value and feasibility — including gaps the assistant should have filed on the wishlist but did not. Reviews are written automatically by the [scheduled script](https://docs.configbox.at/docs/admin-guide/getting-started/schedule-the-recurring-scripts) once a conversation has gone quiet, or by hand with the **Analyze** button (**Re-analyze** once one exists). It takes a few seconds, and the button says so while it runs. A review older than the conversation's last activity is marked stale — re-analyze for a current one. The reviews are also what the [Insights report](https://docs.configbox.at/docs/admin-guide/ai-assistant/run-the-insights-report) reads, so the more conversations carry one, the better that report gets. --- # Read Conversation Insights Page: https://docs.configbox.at/docs/admin-guide/ai-assistant/run-the-insights-report > **Audience:** store owners and product owners · **Scope:** the Conversation Insights screen — > the backlog digest · **Last reviewed:** 2026-08-11 **AI Assistant → Conversation Insights** is the overview: how much is waiting for each group on the [Recommendations screen](https://docs.configbox.at/docs/admin-guide/ai-assistant/send-recommendations-to-your-team), and how the picture moved in the last 30 days — new recommendations, resolved ones, regressions (something marked fixed that visitors hit again), and what was emailed to a contact. ![Conversation Insights: the backlog digest](./img/insights.jpeg) There is nothing to run here any more. Recommendations maintain themselves: the [scheduled script](https://docs.configbox.at/docs/admin-guide/getting-started/schedule-the-recurring-scripts) reviews finished conversations and folds what they reveal into the backlog, deduplicated against everything already known. The cards link straight to each group's list. ## What happened to the reports Before the backlog, this screen generated one-off snapshot reports that you read and re-ran. Those are gone. Their findings were carried into the backlog once, so nothing was lost — and the backlog remembers, deduplicates and tracks status where each report started from scratch. A frozen copy of a list that maintains itself was only ever a way to read something out of date. --- # Work the recommendations Page: https://docs.configbox.at/docs/admin-guide/ai-assistant/send-recommendations-to-your-team > **Audience:** store owners and shop managers · **Scope:** the Recommendations screen — the > backlog, its statuses, the contacts and the email · **Last reviewed:** 2026-08-11 **AI Assistant → Recommendations** is the living to-do list your assistant's conversations produce, split by **who can act on it**. It maintains itself: as conversations are analysed, new evidence either joins a recommendation the list already has or opens a new one. Nothing to generate, nothing to re-read — what you see is current, and the bar above the tabs says so. Every recommendation is backed by the conversations that raised it: the visitor's own words, quoted, with a link into the [journal](https://docs.configbox.at/docs/admin-guide/ai-assistant/read-the-conversation-journal) while the conversation exists. A recommendation without evidence cannot exist. ![The Recommendations screen: groups, evidence and payoff](./img/recommendations.jpeg) Each entry carries the visitor quotes that raised it, how many conversations hit the same wall, and a **payoff** — how much effect it buys for how much effort. ## The five groups | Group | Gets | Typically | |---|---|---| | **Catalog & marketing** | Product explanation gaps | Whoever writes product content | | **Product owner** | Requests visitors made that the shop could not fulfil | Whoever decides what the shop does next | | **Developers** | Likely bugs, each with a ready-made brief | Your developer, agency or in-house team | | **Software vendor** | Feature proposals — abilities the assistant lacked | Your ConfigBox contact | | **The whole team** | Frustrated visitors | Usually the owner or customer experience | Each tab counts what still **needs action**. A group at zero is good news, not an empty screen. ## Working the list Each recommendation can be **marked done** (say what was done — the note stays on the record) or **dismissed** (say why — dismissed items stay dismissed; the analysis will not re-file them). Resolved items collapse into **Done & dismissed** below the list, from where they can be reopened. Two statuses the system sets on its own: - **sent to the contact** — the item was covered by an email from this screen. - **regressed** — the item was marked done, and then *new* conversations hit the same problem. The strongest signal on the screen: a fix that did not hold. ## The contacts and the email Each group has a **name and email address** in Settings → AI Configurator Assistant. Leave a group empty and nothing breaks — its list stays readable, only the send button is disabled. 1. Press **Write an email about these**. The assistant writes a short email from the group's open items — what to do first and why, quoting real visitors. 2. **Read it.** Subject and message are editable; change anything. ![The email the assistant wrote, ready to read and edit](./img/recommendation-email.jpeg) 3. Press **Send it**. Exactly what you see goes out, the covered items are marked **sent**, and the email itself is kept on record — what was sent to whom, when, covering which items. --- # Set up the assistant Page: https://docs.configbox.at/docs/admin-guide/ai-assistant/set-up-the-assistant > **Audience:** store owners and shop managers · **Scope:** the settings that switch the > assistant on and shape its behaviour · **Last reviewed:** 2026-08-11 All settings live in **Settings → AI Configurator Assistant**. The assistant appears on your configurator pages as soon as an API key is saved and the feature is enabled; no other setup is required. ## The API key Create a key in the Anthropic Console (console.anthropic.com) and paste it into the **API key** field. The key stays on your server and is only used for the assistant's own calls. Costs are billed by Anthropic per message — typically single-digit cents per visitor message, depending on the model. ## Choosing the models Two model choices, two different jobs: - **Chat model** — answers visitors live. Latency and cost matter most here. Claude Sonnet is the recommended balance; Claude Haiku is the fastest and cheapest; Claude Opus is the most capable and most expensive. - **Model for the journal analysis** — writes the per-conversation reviews and the Insights report. These run rarely and their quality decides what your team works on, so a bigger model than the chat one usually pays off. ## Persona, greeting, house rules - **Persona** sets the assistant's stance: a neutral **advisor**, a **sales agent** that moves towards completing the purchase, or a precise technical **consultant**. - **Greeting** is the first message in the panel. Leave it empty for the default. - **House rules** are your own standing instructions, one per line — shop-specific facts, what to emphasise, what never to promise. They outrank the built-in guidance, so this is where you put things like "we deliver to Austria and Germany only" or "never promise a delivery date". ## Permissions Three switches decide how far the assistant may go. All three are on by default, and each one only ever lets the assistant do something the visitor could already do themselves on the page. - **Assistant may add the configuration to the cart** — with this off, it advises and selects, but the visitor completes the purchase themselves. - **Assistant may navigate the configurator** — lets it switch pages and point at questions. With this off it can only talk. - **Assistant may change the cart** — lets it change a line item's quantity, remove it, copy it, or reopen it for editing when the visitor asks — the same things the buttons on the cart page do. It always asks before removing anything, and it can never touch a cart that has become an order. The last one is its own switch on purpose: agreeing that the assistant may complete a purchase is not the same as agreeing that it may empty the basket. Reopening and copying a line also need **may navigate the configurator**, because both hand the visitor back to the configurator to finish the job — with that off, the assistant tells them to use the cart's own buttons instead. ## Spend control **Messages per visitor per hour** caps how many messages one visitor can send. It is a lid on API spend, not a security feature. ## The journal settings - **Keep the diagnostic journal** — records every conversation for the [journal](https://docs.configbox.at/docs/admin-guide/ai-assistant/read-the-conversation-journal). Visitors' words are stored verbatim, so mind your privacy policy. - **Journal retention days** — conversations older than this are deleted by the scheduled script. Retention is a promise about visitor data; the deletion only happens when [the script actually runs](https://docs.configbox.at/docs/admin-guide/getting-started/schedule-the-recurring-scripts). - **Analyze conversations automatically** — lets the scheduled script write a lessons-learned review for each conversation once it has gone quiet. You can always analyze single conversations by hand from their journal page instead. - **Also write the journal to a log file** — a plain-text mirror for developers; normally off. ## Feeding the assistant knowledge The settings above shape behaviour — but what makes the assistant *good* is product content: 1. Write real **descriptions** on products, questions and answers. 2. Fill the **detail panes** with specifications, delivery terms and warranty conditions — the assistant quotes them when visitors ask. 3. Watch the [wishlist](https://docs.configbox.at/docs/admin-guide/ai-assistant/work-the-wishlist): every `content` item there is a visitor question your data could not answer, named concretely enough to fix. --- # Work the wishlist Page: https://docs.configbox.at/docs/admin-guide/ai-assistant/work-the-wishlist > **Audience:** store owners, content managers, and whoever talks to the software vendor · > **Scope:** what wishlist items are, who each category is for, and how to act on them · > **Last reviewed:** 2026-08-11 Whenever a conversation exposes something the assistant could not do or answer — or something it noticed was wrong — it files a **wishlist item**, invisibly to the visitor. Each item carries a category that routes it to the people who can fix it, the assistant's description of the gap, and, when a visitor request triggered it, that request in the visitor's own words. Items appear in each conversation's timeline (collapsed to category and title — expand for the full story) and are counted in the journal's **wish** and **unfulfilled** chips. ![A conversation that filed a wish: the chips, and the lessons review naming the gap](./img/conversation.jpeg) The review above the timeline is where the gaps read best: it names the wishlist item that was filed, and — as here — the ones the assistant *should* have filed and did not. ## The categories and who they are for | Category | It means | Who acts on it | |---|---|---| | **content** | A visitor wanted product information your data does not cover — specifications, dimensions, delivery, stock, comparisons. | Content managers: add it to the product's detail panes or descriptions, and the assistant knows it from then on. | | **feature-request** | A legitimate action the assistant had no way to do, or an ability that would have served the visitor better. | The software vendor — this is direct field evidence for what to build next. | | **bug-report** | Something behaved wrongly: a price that does not add up, a selection that will not stick for no visible reason, contradictory data. | Developers / the vendor. | | **translation** | Wording missing or wrong in the visitor's language. | Content managers / translators. | | **ux-friction** | The visitor was confused or misled by how the configurator presents things. | Whoever owns the storefront. | | **other** | Anything else worth passing on. | Triage. | ## How to work them 1. **Content items are the quick wins.** Each one names exactly what information was missing for which product. Put the answer into a detail pane and the gap is closed — the assistant reads panes as product knowledge. 2. **Unfulfilled items deserve priority** — the "unfulfilled" chip means a real visitor asked and left without. That is demand, measured for free. 3. **Feature requests and bug reports** are written to be forwarded: concrete descriptions of the missing ability or the observed misbehavior, with the conversation reference for context. 4. For volume, don't read item by item — run the [Insights report](https://docs.configbox.at/docs/admin-guide/ai-assistant/run-the-insights-report), which groups wishlist items across conversations, deduplicates common causes and ranks them by effect and effort. The long-term idea: this diagnostic data is what your installation can eventually share with the vendor, so content gaps, feature demand and field bugs surface across all stores — not just yours. --- # Customers, taxes, shipping & payment Page: https://docs.configbox.at/docs/admin-guide/commerce/ > **Audience:** store admins · **Scope:** the commercial rules around the configurator · **Last reviewed:** 2026-07-20 **TL;DR** — Four questions decide every checkout: **who** is buying (customer group → B2B/B2C mode, permissions, discounts), **in what currency**, **how it's taxed** (tax class × the customer's place), and **how it ships and gets paid** (country → zone → shipping methods; group/country → payment methods). Each has its own screen; this page explains how they interlock. > **Platform note (Magento 2):** this whole system does **not apply** on Magento-hosted stores — > customers, currencies, taxes, shipping and payment are set up in Magento, and the CBX > screens described here are hidden there. See [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/). ## Articles 1. **[Set up customer groups](https://docs.configbox.at/docs/admin-guide/commerce/set-up-customer-groups)** — B2B/B2C, buy-vs-quote permissions, volume discounts. 2. **[Manage currencies](https://docs.configbox.at/docs/admin-guide/commerce/manage-currencies)** — base vs default, multipliers, adding a currency. 3. **[Set up taxes](https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes)** — tax classes, place-based overrides, the EU VAT flags. 4. **[Set up shipping](https://docs.configbox.at/docs/admin-guide/commerce/set-up-shipping)** — shippers, zones, weight-band methods. 5. **[Set up payment methods](https://docs.configbox.at/docs/admin-guide/commerce/set-up-payment-methods)** — providers, surcharges, availability limits. ## Customer groups — the policy hub **Settings → Customer Groups** (also embedded in the Settings screen). A customer belongs to one group (guests get the default group set in **Settings**); the group decides: - **Tax display mode** — **B2C** (tax-inclusive prices) or **B2B** (net prices). - **Permissions** — whether the group sees prices at all, can check out, can save carts, can request quotations (and whether quote PDFs download or come attached to the email). This is how you run "consumers buy, trade requests quotes" setups. - **Volume discounts** — up to five tiers ("from €X net order value: Y% off"), separately for regular and recurring totals; the highest qualifying tier applies automatically in the cart. ![The customer groups list](./img/customer-groups.jpeg) ## Currencies **Base** currency is what you author every price in; other currencies convert via their **multiplier**. **Default** is what visitors see first. Symbol, code and active flag per currency. ![Currencies](./img/currencies.jpeg) ## Taxes and geography **Tax Classes** (embedded in Settings) hold a name and a **default rate**; products, shipping and payment surcharges reference a class. The **Countries** screens (Countries → States → Counties → Cities) can override any class's rate per place — the most specific place wins. Countries also carry the **VAT free** and **EU VAT area** flags that drive B2B reverse-charge handling for valid VAT IDs. ![Countries](./img/countries.jpeg) ## Shipping Three pieces under **Shipping**: **Shippers** (the carrier names), **Shipping Zones** (country groups like "EU", "Domestic"), and **Shipping Methods** — the actual options offered at checkout, each tied to a zone, a **cart-weight band** (min/max), a price, a delivery-time text and a tax class. The customer's country picks the zone; the cart weight picks the band. Shipping can be disabled store-wide in **Settings** for digital/service products. ![Shipping methods](./img/shipping-methods.jpeg) ## Payment methods Each method names its payment provider and its configuration, an optional **surcharge** (fixed and/or percentage, clamped by min/max, taxed per its tax class), and can be restricted to certain **customer groups** and **countries** — only methods valid for the buyer are offered. ![Payment methods](./img/payment-methods.jpeg) ## How it combines at checkout 1. The customer's **group** sets pricing mode, permissions and discounts. 2. Their **currency** converts all amounts. 3. Each line's **tax class** rate resolves by their place (city → county → state → country → default), with VAT-free/EU rules applied. 4. Their **country → zone** plus cart **weight** select the shipping options. 5. Their **group + country** select the payment options; the chosen one adds its surcharge. --- # Manage currencies Page: https://docs.configbox.at/docs/admin-guide/commerce/manage-currencies > **Audience:** store admins · **Scope:** the Currencies manager · **Last reviewed:** 2026-07-20 **What this does** — Controls which currencies customers can shop in and how amounts convert. Two distinct roles matter here, and mixing them up is the classic mistake: - **Base** — the currency you *author* in. Every price you type anywhere in CBX (products, answers, calculations, shipping) is in the base currency. - **Default** — the currency a visitor *sees first*. Customers can switch between the active currencies. ## Steps 1. Open **Settings** → the embedded **Currencies** manager: ![The Currencies manager](./img/currencies.jpeg) 2. To add a currency: **Add**, then fill **Title**, **Currency Symbol** (€, $), **Currency Code** (ISO, e.g. `EUR`), and the **Multiplier** — the conversion factor *from the base currency* (base itself is always `1`). With EUR as base and a rate of 1 € = 1.38 $, USD's multiplier is `1.38`. 3. Set **Active** to Yes to offer it to customers. 4. Use the list's action buttons on a ticked row: **Make Default** (what visitors see first) and **Make Base** (what prices are authored in). ## What happens next Every displayed amount — configurator, cart, checkout, order emails — converts through the multiplier, unless a product/answer carries an explicit **price override** for that currency (overrides beat conversion; use them for "pretty" round prices in a foreign currency). ## Good to know - **Multipliers are not live exchange rates.** They stay where you set them — review them on a schedule if you sell in multiple currencies seriously. - **Think twice before changing the base currency** on a running store: every entered price keeps its number but changes meaning. Changing the *default* is harmless. - Orders snapshot the currency and rate at purchase time — old orders don't move when you update a multiplier. --- # Payment providers Page: https://docs.configbox.at/docs/admin-guide/commerce/payment-providers > **Audience:** store admins · **Scope:** the built-in providers on the payment method form · **Last reviewed:** 2026-08-15 **What this covers** — Each payment provider CBX ships with: which markets and payment types it serves, the fields its settings block asks for, where to get the credentials, and how to test it before going live. Set up the method itself first — see [Set up payment methods](https://docs.configbox.at/docs/admin-guide/commerce/set-up-payment-methods). ## How providers work in general - **Pick the provider on the payment method form**; its settings appear right below the choice. Required fields carry a marker; the status note under them turns green when the provider is ready. A method whose provider is not ready is never offered at checkout. - **The customer pays on the provider's own page** (or, for Stripe's on-site mode, in fields the provider renders into your page). Card data never touches your store — that is what keeps you out of card-security certification scope. - **Every provider has a test mode.** Keep it on while trying things out: payments run against the provider's sandbox with test cards, and the payment records are marked as test. Switch to live only after a full test round trip. - **Secrets stay secret.** API keys are stored encrypted and never displayed again — a filled field shows "a value is stored". Blank keeps it, typing replaces it. - **Webhooks** are the provider calling your store the moment money moves. Providers that need the webhook address registered in their dashboard show the exact URL as a note among their settings; copy it over. Providers without that note handle it automatically. Either way the store also re-checks pending payments on its own, so a missed call never loses a payment. ## DemoPay (test provider) The built-in fake provider. It moves no money, needs no account, and can simulate every checkout experience — hosted page, on-site card fields, wallet button, vouchers, even payment confirmations that arrive late. Use it to try the whole order flow end to end, demo the store, or train staff. The card number decides the outcome on its fake payment page (for example a card ending in 0002 declines). - Fields: **Flow to simulate**, **Shared webhook secret** (any random string), and a note that DemoPay never moves real money. ## Stripe Cards, wallets and many local methods across the US, Canada and Europe. Two ways to present it: the hosted Stripe page, or Stripe's card fields rendered inside your checkout. - Fields: **Secret key** (required), Publishable key (needed for the on-site mode), Webhook signing secret, Input mode. - Credentials: dashboard.stripe.com → Developers → API keys. Test keys start with `sk_test_`. - Webhook: register the URL shown in the settings note at Stripe → Developers → Webhooks; the signing secret it gives you goes into the Webhook signing secret field. ## PayPal The most widely recognized wallet in the US and Europe. - Fields: **Client ID** (required), **Client secret** (required), test mode. - Credentials: developer.paypal.com → Apps & Credentials → create a REST app. Sandbox and live are separate apps with separate credentials. ## Mollie One account covering the common European methods — iDEAL, Bancontact, EPS, cards and more. Which methods appear on Mollie's payment page is chosen in your Mollie dashboard, not in CBX. - Fields: **API key** (required), test mode. - Credentials: my.mollie.com → Developers → API keys. The test key starts with `test_` and works without business verification. ## Klarna Pay now, pay later and financing, strongest in German-speaking and Nordic markets. Klarna decides which of its products the customer sees, based on your merchant agreement. - Fields: **API username** (required), **API password** (required), Region, test mode. - Credentials: the Klarna merchant portal issues the API username/password pair; "playground" credentials are the test ones. ## Authorize.net The long-established US and Canada card gateway. - Fields: **API login ID** (required), **Transaction key** (required), Signature key, mode. - Credentials: the Authorize.net merchant interface → Account → API Credentials & Keys. A free sandbox account is available at developer.authorize.net. - Webhook: register the URL from the settings note under Account → Webhooks, and store the signature key so the calls can be verified. Without it, the store still confirms payments by re-checking, just a little later. ## Square Popular with US small and mid-size merchants; the customer pays on a Square-hosted page. - Fields: **Access token** (required), **Location ID** (required), Webhook signature key, mode. - Credentials: developer.squareup.com → your app → sandbox or production access token, and the location the payments should book to. - Webhook: subscribe the URL from the settings note in the Square developer dashboard; the subscription shows the signature key. The registered URL must match the note exactly. ## Adyen The enterprise-grade European provider with global card and local-method coverage; the customer pays on Adyen's hosted checkout page. - Fields: **API key** (required), **Merchant account** (required), Webhook HMAC key, Live URL prefix (live mode only), test mode. - Credentials: the Adyen Customer Area → Developers → API credentials. The merchant account is the account code payments run through. - Webhook: create a "standard webhook" in the Customer Area with the URL from the settings note; it issues the HMAC key. Going live additionally needs the live URL prefix shown in the Customer Area. ## Saferpay (Worldline) The incumbent gateway in Switzerland, France, Germany and Benelux. - Fields: **Customer ID** (required), **Terminal ID** (required), **JSON API username** (required), **JSON API password** (required), mode. - Credentials: the Saferpay Backoffice shows customer and terminal id; create a "JSON API user" there for the username/password. A self-serve sandbox exists at test.saferpay.com. ## PostFinance Checkout Switzerland's house solution: PostFinance Card, TWINT, e-finance and cards on one hosted page. - Fields: **Space ID** (required), **Application user ID** (required), **Authentication key** (required), mode. - Credentials: sign up at checkout.postfinance.ch; every account includes a test space. Create an application user with access to the space — it shows its authentication key once, at creation. - Webhook: add a webhook for transactions in the space settings using the URL from the settings note. ## Nexi Checkout The Nexi/Nets group's hosted checkout, covering Italy and the Nordics. - Fields: **Secret key** (required), **Terms URL** (required — a link to your store's payment terms page, which their checkout displays), Webhook secret, test mode. - Credentials: the Nexi group portal issues separate test and live secret keys. - Webhook: optional — invent a random string as the webhook secret and the store registers the notification automatically with each payment. ## PayU Poland's leading provider and a CEE staple: BLIK, Polish bank transfers and cards. - Fields: **POS ID** (required), **OAuth client secret** (required), Second key (MD5), mode. - Credentials: the PayU merchant panel shows all three per point of sale; a self-serve sandbox is available. - The second key verifies PayU's payment notifications — store it, or confirmations rely on re-checking alone. ## Trustly Direct bank payments (open banking), strongest in Scandinavia and growing across Europe. No cards involved — the customer pays straight from their bank account. - Fields: **Username** (required), Password, **Merchant private key** (required), **Trustly public key** (required), test mode. - Credentials: no self-serve signup — Trustly's integration team provides test credentials and exchanges security keys with you during merchant onboarding. ## Bank transfer (Swiss QR-bill) Not an online provider: the thank-you page shows your account details, a structured payment reference and the official Swiss QR code the customer can scan in their banking app. You mark the payment as settled when it appears on your bank statement — see [Track payments](https://docs.configbox.at/docs/admin-guide/orders/track-payments). - Fields: **IBAN** (required), **Account holder** (required), street, postal code and city, country code. --- # Set up customer groups Page: https://docs.configbox.at/docs/admin-guide/commerce/set-up-customer-groups > **Audience:** store admins · **Scope:** the customer group form · **Last reviewed:** 2026-07-20 **What this does** — Customer groups are where your commercial policy lives. One form decides, per segment: do they see tax-inclusive or net prices, may they buy or only request quotes, and which volume discounts apply. Typical setups: one group ("everyone buys"), or a consumer/trade split where consumers check out and trade customers get quotes and negotiated discounts. ## Before you start - Decide your segments and what each may do. Fewer groups is better — every group is a pricing and permissions surface you'll maintain. - Know which platform (site) user group corresponds to each segment — that link is how logged-in users land in the right CBX group. ## Steps 1. Open **Settings** and go to the embedded **Customer Groups** manager; open a group or add one: ![The customer group form](./img/customer-group-edit.jpeg) 2. In the top section: - **Name** — for the back office only. - **Platform Group** — the site user group that maps here. A logged-in customer's CBX group follows their site account; visitors without an account fall into the **default customer group** chosen in **Settings → Checkout**. - **Tax display mode** — **B2C** (prices shown tax-inclusive) or **B2B** (net prices, tax added at checkout). This one switch changes price display store-wide for the group. 3. In **Permissions**, shape what the group can do — each is a plain Yes/No: - **Enable price display in configurator and cart** — turn off for a browse-only or "prices on request" experience. - **Enable checkout** — may they place real orders? - **Enable Save Order** — may they save a cart for later? - **Enable Quotation Request** — may they ask for a quote instead of buying? - **Automated quotation download** / **Quote PDF attachment in notification** — whether a requested quote is instantly downloadable and/or attached to the email. 4. In **Discount Levels**, add up to five volume tiers — each is "for net order totals starting at X: a percentage or a fixed amount off, with a label the customer sees". Regular and recurring totals have separate tiers. The **highest tier the cart qualifies for** applies automatically. 5. **Save**. ## What happens next Every visitor and customer in the group immediately gets its pricing mode, permissions and discounts — configurator, cart and checkout included. The form's "in use" list at the bottom shows which customers currently sit in the group. ## A worked example — consumer/trade split - *Retail* (default group): B2C · checkout on · quotations off · no discounts. - *Trade*: B2B · checkout on · quotations on with PDF attachment · tiers "from €1,000: 5%", "from €5,000: 10%". A trade login sees net prices, can order or request a quote, and the cart shows "Volume discount 10%" by itself once the total crosses €5,000. ## Good to know - **The default group serves guests.** Whatever you set there is your store's public face — check it first when "everyone" reports a pricing oddity. - Prices can also be **pinned per group** (price overrides on products and answers) — use overrides for a few special prices, discounts for across-the-board percentages. - Payment methods can be **restricted per group** (e.g. invoice payment for trade only) — that's on the [payment method form](https://docs.configbox.at/docs/admin-guide/commerce/set-up-payment-methods). - Rules can read the customer's group — so even the *configurator* can differ per segment (see [Rules](https://docs.configbox.at/docs/admin-guide/rules/)). --- # Set up payment methods Page: https://docs.configbox.at/docs/admin-guide/commerce/set-up-payment-methods > **Audience:** store admins · **Scope:** the payment method form · **Last reviewed:** 2026-08-15 **What this does** — Defines how customers can pay: which payment provider handles each option, what surcharge (if any) it adds, and who gets offered it. A store typically runs a handful — say bank transfer, PayPal and a card provider. ## Steps 1. Go to **Payment Methods**, open one or **Add**: ![A payment method bound to a provider](./img/payment-method-provider.jpeg) 2. The essentials: - **Title** per language — what checkout shows ("Bank transfer"). - **Payment provider** — who handles the money. Choosing one immediately shows that provider's own settings right below, no save needed. Fields marked as required are what the provider needs before it can take a payment — see [Payment providers](https://docs.configbox.at/docs/admin-guide/commerce/payment-providers) for every provider's fields and where its credentials come from. - The **status note** under the provider's fields tells you where you stand: an orange note names what is still missing, a green one confirms the provider is ready. - **Active** — offered or not. 3. Optional surcharge — use sparingly, and mind local law: - **Static extra charge** plus **Extra charge percentage** of the order; the combined result is clamped between **Minimum** and **Maximum Extra Charge**, and taxed per the method's **Tax Class**. 4. Optional availability limits: - **Available for these customer groups** — e.g. "payment on invoice" for the trade group only. - **Available for these countries** — the country list is collapsed behind a counter; expand it, or type in the filter box to find countries quickly. **Select All** and **Deselect All** apply to what the filter currently shows. 5. **Save**, and order the methods in the list the way checkout should present them. ## What happens next Checkout offers each active method whose group and country restrictions match the buyer — but **only if its provider is fully configured**. A half-configured method saves fine (handy while you wait for credentials) and is simply not shown to customers until the status note turns green. When a customer pays, the order first waits on **Awaiting payment**; the provider's confirmation flips it to **Paid** (or to *Incorrect amount paid* if the amounts disagree). Every attempt is recorded — see [Track payments](https://docs.configbox.at/docs/admin-guide/orders/track-payments). ## Good to know - **Credentials are stored encrypted** and are never shown again: a saved key displays as "a value is stored". Leave the field blank to keep it; type a new value to replace it. - Some providers show a note with a **webhook URL to register** in the provider's own dashboard. Doing that lets payment confirmations arrive even when the customer closes the browser right after paying — worth the two minutes. - **Test the full round trip** for every online provider in their sandbox/test mode before going live: order → pay → order lands on *Paid* → the *Paid* notification email arrives. - The **Legacy connector** choice remains for methods set up before the provider system; new methods should always pick a provider. --- # Set up shipping Page: https://docs.configbox.at/docs/admin-guide/commerce/set-up-shipping > **Audience:** store admins · **Scope:** the three Shipping screens · **Last reviewed:** 2026-07-20 **What this does** — Decides which delivery options a customer is offered and at what cost. The model is simple and worth internalizing before filling forms: > The customer's **country** selects the **zone** · the cart's **weight** selects the band · > every **shipping method** matching zone + band is offered, with its price and delivery time. ## Before you start - Sketch your zones (e.g. *Domestic*, *EU*, *Rest of World*) and your price logic per zone (flat? weight brackets?). - If prices depend on weight, make sure your answers carry **Weight** values — cart weight is the sum of the base weight and the selected answers. ## Steps 1. **Shippers** (under **Shipping**) — add your carriers ("DHL", "UPS"). These are labels that group methods; nothing more to configure. 2. **Shipping Zones** — create each zone and tick its member countries. (A country can also be assigned to zones from its own form.) 3. **Shipping Methods** — one entry per offer the customer can pick: ![The shipping method form](./img/shipping-method-edit.jpeg) - **Title** per language — what checkout shows. - **Shipper** and **Zone** — who carries it, where it applies. - **Minimum / Maximum Weight** — the cart-weight band (kg) this method covers. - **Delivery Time** — a plain "5 days" style promise, shown to the customer. - **Price** and **Tax Class** — what it costs and how that cost is taxed. - **Active** on, **Save**. For weight brackets, create several methods with the same title and adjoining bands (0–5 kg €10, 5–20 kg €25 …) — the cart weight picks the right one automatically. ## What happens next Checkout offers every active method whose zone contains the customer's country and whose band contains the cart weight. The chosen method's price and delivery time land on the order (and in the live overview earlier, if **Show delivery options** is on in **Settings**). ## Good to know - **A customer sees no shipping options?** Their country is in no zone, or the cart weight falls outside every band — those are the only two causes. Make bands overlap-free but gapless (end one at 5, start the next at 5). - **Digital or service products:** switch shipping off entirely with **Settings → Checkout → Disable Shipping** — the whole step, address fields included, disappears. - Weight itself can be computed per question/answer via a **weight calculation** — see [pricing](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from); the same mechanism feeds the shipping weight. - **External ID** is for integrations that map methods to an outside system; leave it empty otherwise. --- # Set up taxes Page: https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes > **Audience:** store admins · **Scope:** tax classes + the geography screens · **Last reviewed:** 2026-07-20 **What this does** — Sets what tax is charged, where. Two pieces cooperate: **tax classes** (named rate buckets like *Standard* and *Reduced* that products, shipping and payment surcharges point at) and the **geography records** (which can override a class's rate per place). For most stores this is a fifteen-minute, set-once job. ## How the rate is found For each order line, CBX takes the line's **tax class** and looks for that class's rate at the customer's place, most specific first: > **City → County → State → Country → the class's default rate.** Two country flags trump the chain: **VAT free** (no VAT for orders to this country) and **In EU VAT Area** (enables EU B2B handling — a valid foreign VAT ID makes the order reverse-charge, and the order prints the "tax liability is shifted" note). ## Steps 1. **Define the classes.** Open **Settings** → the embedded **Tax Classes** manager. Each class has a **Name** and a **Default Tax** rate — the fallback when no place overrides it. One *Standard* class is enough for many stores; add *Reduced* etc. only if you sell mixed-rate goods. 2. **Set place-specific rates where needed.** Open **Countries**, open a country: ![The country form with its Tax Override section](./img/country-edit.jpeg) - **Tax Override** — enter this country's rate for any class (leave empty to inherit the class default). - **VAT free** / **In EU VAT Area** — the special-case flags described above. - **Zones** — which shipping zones the country belongs to (that's for [shipping](https://docs.configbox.at/docs/admin-guide/commerce/set-up-shipping), managed here for convenience). - The same Tax Override section exists on **States**, **Counties** and **Cities** for region-level taxes (US-style setups); populate only the levels you actually need — the address form shows only populated levels. 3. **Point things at classes.** Products (per pricing section), shipping methods and payment surcharges each carry a **Tax Class** field — that's the whole wiring. ## What happens next Checkout resolves each line's rate from the buyer's address (before an address is known, the **Default Country** from **Settings → Checkout** is assumed — set it to your home market so walk-in visitors see the right prices). Whether prices *display* net or gross follows the customer group's **B2B/B2C** mode; the resolution above decides what is *charged*. ## Good to know - **Check the reverse-charge path** if you sell B2B in the EU: a test order with a valid foreign VAT ID should come out tax-free with the shifted-liability note on the order. - The customer's VAT ID lives on their [customer record](https://docs.configbox.at/docs/admin-guide/orders/manage-customers); whether the field is shown/required per flow is the **Customer Fields** matrix. - Rates changed here apply to **new** carts immediately; placed orders keep their snapshotted tax. - A missing shop country (fresh installs) is flagged on the **Dashboard** — fix that before anything else tax-related. --- # Getting started Page: https://docs.configbox.at/docs/admin-guide/getting-started/ > **Audience:** store admins · **Scope:** orientation before any real work · **Last reviewed:** 2026-08-01 **TL;DR** — Everything you manage lives behind one menu in your site's admin area. Almost every CBX screen is either a **list** (find, sort, publish, copy, delete) or an **edit form** (fields grouped into collapsible sections, Save on top) — learn those two once and you can work every screen in the store. The only thing that depends on your host is where that menu lives and how your storefront pages get built — so start by picking your platform. ## 1. Pick your platform CBX runs inside Joomla, WordPress or Magento 2. Read the one article for *your* host and ignore the others: - **[CBX on Joomla](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-joomla)** — logging in at `/administrator`, **Components → CBX**, and building your storefront with CBX menu items. - **[CBX on WordPress](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-wordpress)** — logging in at `/wp-admin`, the CBX menu entry, and putting CBX content on your own pages with shortcodes. - **[CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-magento2)** — Magento is the shop, CBX is the configurator; this pointer page sends you to the guide's dedicated [Magento 2 system](https://docs.configbox.at/docs/admin-guide/magento2/). ## 2. Follow the shared path Everything past the host article is the same on every platform: 1. **[Log in and find CBX](https://docs.configbox.at/docs/admin-guide/getting-started/log-in-and-find-cbx)** — where the admin area is and what the CBX menu contains. 2. **[Run the setup wizard](https://docs.configbox.at/docs/admin-guide/getting-started/run-the-setup-wizard)** — the first-run assistant: licence key, languages, taxes, store information and currencies, and which of those are expensive to change later. 3. **[Work the list and edit screens](https://docs.configbox.at/docs/admin-guide/getting-started/the-admin-screens)** — the shared conventions: searching and filtering, adding, editing, publish/unpublish, ordering, copying, and how translatable fields work. 4. **[Read the dashboard](https://docs.configbox.at/docs/admin-guide/getting-started/check-the-dashboard)** — the health-check screen: what its warnings mean and which ones need action. ## The CBX menu at a glance | Menu item | What it manages | Read | |---|---|---| | **Dashboard** | Health checks, performance tips, update and license status | [Check the dashboard](https://docs.configbox.at/docs/admin-guide/getting-started/check-the-dashboard) | | **Products** | The product tree — products, their pages, questions and answers | [Products](https://docs.configbox.at/docs/admin-guide/products/) | | **Product Lists** | The catalogs your storefront shows | [Manage product lists](https://docs.configbox.at/docs/admin-guide/products/manage-product-lists) | | **Calculations** | The formulas, code expressions and matrices behind dynamic prices | [Pricing](https://docs.configbox.at/docs/admin-guide/pricing/) | | **Orders** | Every order, quotation and saved cart | [Orders](https://docs.configbox.at/docs/admin-guide/orders/) | | **Customers** | Customer records: addresses, VAT numbers, group membership | [Manage customers](https://docs.configbox.at/docs/admin-guide/orders/manage-customers) | | **Reviews** | The product-review moderation queue | [Moderate reviews](https://docs.configbox.at/docs/admin-guide/orders/moderate-reviews) | | **Countries** | Geography: countries, states, counties, cities — and place-based tax rates | [Set up taxes](https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes) | | **Shipping** | Shippers, shipping zones and shipping methods | [Set up shipping](https://docs.configbox.at/docs/admin-guide/commerce/set-up-shipping) | | **Payment Methods** | How customers can pay, incl. surcharges and availability | [Set up payment methods](https://docs.configbox.at/docs/admin-guide/commerce/set-up-payment-methods) | | **Store Information** | Your company identity — used on invoices, quotes and emails | [Settings](https://docs.configbox.at/docs/admin-guide/settings/) | | **Customer Fields** | Which address/customer fields appear (and are required) in each flow | [Settings](https://docs.configbox.at/docs/admin-guide/settings/) | | **Notifications** | The status-triggered emails to customers and the shop manager | [Set up order emails](https://docs.configbox.at/docs/admin-guide/orders/set-up-order-emails) | | **Settings** | The global configuration screen | [Settings](https://docs.configbox.at/docs/admin-guide/settings/) | > **Platform note (Magento 2):** on Magento-hosted stores the menu shows only **Dashboard, > Products, Calculations** and **Settings** — Magento itself handles the other jobs, so those > entries are deliberately absent, not broken. [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/) > explains who does what. --- # Read the dashboard Page: https://docs.configbox.at/docs/admin-guide/getting-started/check-the-dashboard > **Audience:** store admins · **Scope:** the CBX Dashboard screen · **Last reviewed:** 2026-07-20 **What this does** — The Dashboard is CBX's health check: the first place to look when something misbehaves, and worth a glance after any bigger change to your site. ![The CBX dashboard](./img/dashboard.jpeg) ## What the panels tell you - **Health Check** — actionable problems, each with a short explanation. Typical entries: a missing shop country, folders the server can't write to (uploads and PDFs fail silently without this), too little PHP memory, a missing or expired license, or a halted update. **If customers report something broken, read this list first.** - **Suggestions to improve performance** — server/caching tips. Nice to fix, never urgent. - **Software Update** — the installed CBX version and whether a newer release exists, with an update link. - **Your License** — your license key and its status. An expired or missing license shows a warning here (and in Health Check) but does **not** switch your store off. - **CBX Manual** — a link to the online manual. - **Current server status** — database/cache usage figures; useful to your hosting or support contact when diagnosing performance. - **News** — release announcements from the CBX team. ## Good to know - The dashboard only *reports* — nothing on it changes your store. It is always safe to look. - A **"failed update detected"** warning means a database update didn't complete and further updates are paused until it's resolved — contact whoever maintains your site; don't ignore it, as parts of the admin can misbehave until it's fixed. - Warnings about PHP settings, folder permissions and database privileges are for your **hosting provider or developer** — forward the exact wording; it names precisely what needs changing. --- # Log in and find CBX Page: https://docs.configbox.at/docs/admin-guide/getting-started/log-in-and-find-cbx > **Audience:** store admins · **Scope:** getting into the CBX admin area · **Last reviewed:** 2026-07-21 **What this does** — Gets you into the back office where all store management happens, and shows you the menu you'll use for everything else in this guide. ## Before you start - You need an admin account for your website with access to CBX. If you don't have one, ask whoever set up your site. ## Steps 1. Open your site's **administrator area** in a browser. On a Joomla-hosted store that is your site's address followed by `/administrator`; on a WordPress-hosted store it is `/wp-admin`. ![The administrator login screen](./img/admin-login.jpeg) 2. Enter your **username** and **password** and sign in. 3. Open the CBX area. On Joomla: **Components → CBX** — see [Run CBX on a Joomla site](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-joomla) for everything Joomla-specific. On WordPress: **CBX** in the left admin menu — see [Run CBX on a WordPress site](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-wordpress) for everything WordPress-specific. On Magento 2: **Configbox → Administration** in the admin sidebar — see [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-magento2) for everything Magento-specific. The CBX screens themselves are identical on every host. 4. You land on the **Dashboard**, with the CBX menu on the left: ![The CBX dashboard with the menu on the left](./img/dashboard.jpeg) ## What happens next Every article in this guide starts from this menu — when a step says "go to **Products**" or "open **Settings**", it means this CBX menu, not your site's general admin menus. ## Good to know - **Menu groups expand.** Entries with a **+** (Products, Countries, Shipping) expand to sub-entries; the **Products** entry is both a link (the product tree) and a group. - **Two ways to edit.** Besides the back office, managers who are logged in on the **storefront** see edit buttons when hovering over products, questions and answers — the same edit forms open in place. Great for tweaking while seeing what the customer sees. - If your admin session expires, CBX brings you back to the login screen — nothing you had already **saved** is lost. --- # Run CBX on a Joomla site Page: https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-joomla > **Audience:** store admins on Joomla-hosted stores · **Scope:** the few things that are specific to Joomla · **Last reviewed:** 2026-07-21 **What this does** — Shows you where CBX lives in the Joomla administrator and how your storefront pages get built, which on Joomla means **menu items**. Everything else in this guide — products, rules, pricing, commerce, orders — is the same on every host, and its screenshots are taken from a Joomla store, so the rest of the guide will look exactly like your own admin. ## Before you start - You need a Joomla account with access to the administrator and to the CBX component. If you don't have one, ask whoever runs your site. ## Log in and find CBX 1. Open your site's address followed by `/administrator` and sign in. 2. Go to **Components → CBX**. You land on the CBX **Dashboard**, with the CBX menu on the left of its screen — the menu the rest of this guide refers to. From here on, when an article says "go to **Products**" or "open **Settings**", it means that CBX menu, not Joomla's. ## Build your storefront with menu items Products, product lists, the cart and the account area only reach your visitors once a **Joomla menu item** points at them. This is the one job that works differently on other hosts, where a shortcode or a catalog product does the same job. 1. Go to **Menus → `` → Add New Menu Item**. 2. Give it a **Title**, then next to **Menu Item Type** click **Select**. 3. Open the **CBX** group and pick a type: ![The CBX group of Joomla's Menu Item Type picker](../img/joomla-menu-item-types.jpeg) 4. Fill in whatever the type asks for — a **Product List** item asks which list, a **Product** item which product. 5. **Save**. ### What each type is for | Menu Item Type | Use it for | |---|---| | **Product List** | Your shop page — one of the lists you built under **Product Lists** | | **Product** | A landing page for one specific product | | **Configurator Page** | A configurator step on its own page | | **Shopping Cart** | The cart | | **Customer Account Page** | The customer's account — orders, quotations, addresses | | **Customer Login Page** / **Customer Registration Page** / **Edit Customer Account Page** | The individual account screens, when you want them separately reachable | | **Order Listing for Shop Managers** | An order list on the front end, for your shop managers | | **Terms and Conditions Page** / **Refund Policy Page** | The legal pages the checkout links to | | **Custom** | An anchor for a custom page built for you by a developer | **Most stores need surprisingly few.** A **Product List** item, a **Shopping Cart** item and a **Customer Account Page** item are usually the whole set: products and their configurator steps get their addresses *underneath* the product list automatically, so you do **not** need a menu item per product or per configurator page. Add a **Product** or **Configurator Page** item only when you want something to live somewhere else in your site structure. There is no *Checkout* menu item type — customers reach the checkout from the cart. ## Clean URLs Joomla decides how your addresses look, under **System → Global Configuration → Site → SEO**. With Joomla's **Search Engine Friendly URLs** turned on, a configurator page reads like `/en/demo-products/car/motor.html`; with it off, everything still works but you get long `index.php?option=…` addresses instead. Those readable path segments come from the **SEF Segment** field on each product and page — see [Add a product](https://docs.configbox.at/docs/admin-guide/products/add-a-product). It is per language, and it must be unique: if you reuse one, CBX refuses to save and tells you which product already has it. ## What else gets installed Installing CBX adds a few Joomla extensions besides the component itself. You don't need to configure them, but it helps to recognise them: | Extension | Where | What it does | |---|---|---| | **System - CBX** | **System → Plugins** | Lets CBX run on your site — leave it enabled | | **User - CBX** | **System → Plugins** | Keeps Joomla accounts and CBX customers in step | | **Authentication - CBX** | **System → Plugins** | Lets customers sign in during checkout | | **CBX - Console commands** | **System → Plugins** | Command-line tools for your developer or host | | **CBX Currencies** | **Content → Site Modules** | An optional currency switcher you can publish in a template position | ## Good to know - **One login for your customers.** Shoppers use their normal Joomla account; someone who fills a cart as a guest and then logs in keeps that cart. - **Multilingual sites:** CBX translates its own texts (product names, questions, answers, SEF segments) in its edit screens — the flag icons next to translatable fields — while Joomla handles the menus and pages around them. Give each language its own set of CBX menu items, as the demo store does. - **Your template wraps CBX.** The configurator, cart and checkout render inside your normal template, so they inherit its fonts, colours and content width. A cramped configurator is nearly always the template's width, not a CBX setting. - **CBX settings are not in Joomla's Global Configuration.** They live at **CBX → Settings**. ## Troubleshooting - **No CBX under Components?** Your account lacks access to the component, or the extension isn't installed — ask your site administrator. - **A storefront page shows "not found" or lands on the wrong page?** The menu item for that view is missing or unpublished. Check **Menus** for a published item of the matching type. - **URLs look like `index.php?option=com_configbox&…`?** Joomla's Search Engine Friendly URLs are off — turn them on in **Global Configuration → Site → SEO**. - **CBX refuses to save a product because the SEF segment is taken?** Another product already uses that segment in that language. Open the product's **Others** section and enter a different one. --- # Run CBX on a Magento 2 site Page: https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-magento2 > **Audience:** store admins on Magento 2-hosted stores · **Scope:** pointers to the Magento-specific documentation · **Last reviewed:** 2026-08-01 **What this does** — Tells you the little that is different on Magento before you continue with the shared path, and where the rest of the Magento story lives. Magento changes more than the other hosts do — it has [its own system in this guide](https://docs.configbox.at/docs/admin-guide/magento2/), so this page stays short on purpose. ## The essentials - **You reach CBX via Configbox → Administration** in the Magento admin sidebar. From there, the screens are the same as on every other host. - **CBX is the configurator; Magento is the shop.** You build products, questions, rules and prices in CBX and attach them to Magento catalog products — cart, checkout, orders, customers, emails, taxes, shipping and payment are all Magento's job. - **Your CBX menu shows only four entries** — **Dashboard, Products, Calculations, Settings**. The rest of the menu this section describes is deliberately absent, not broken. - **The setup wizard is shorter too:** it stops after the language settings, because taxes, store information and currencies are Magento's own settings. ## Where to read on - **[CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/)** — the Magento system of this guide: the who-does-what table, which parts of the guide apply to you, and how configured products show up in Magento carts and orders. **Read it before anything else in this guide.** - **[Connect a CBX product to a Magento product](https://docs.configbox.at/docs/admin-guide/magento2/connect-a-magento-product)** — the one Magento-specific task: making a catalog product configurable. - **[Magento 2 platform guide](https://docs.configbox.at/docs/platform/magento2/magento2_platform_guide)** — for developers and integrators: installation, command line, technical behavior. --- # Run CBX on a WordPress site Page: https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-wordpress > **Audience:** store admins on WordPress-hosted stores · **Scope:** the few things that work differently on WordPress · **Last reviewed:** 2026-07-25 **What this does** — Shows you where CBX lives in the WordPress admin and how CBX content appears on your site's pages. Everything else in this guide — products, rules, pricing, commerce, orders — works exactly the same whether your store runs on WordPress, Joomla or Magento, so this is the only WordPress-specific article you need. ## Before you start - You need a WordPress account with permission to edit pages — that's the level CBX requires for its admin screens. If you don't have one, ask whoever runs your site. ## Log in and find CBX 1. Open your site's address followed by `/wp-admin` and sign in with your WordPress username and password. ![The WordPress login screen](../img/wordpress-admin-login.jpeg) 2. In the left admin menu, click **CBX**. You land on the CBX **Dashboard**, with the CBX menu on the left of its screen: ![The CBX dashboard inside the WordPress admin](../img/wordpress-dashboard.jpeg) From here on, the screens are identical to every other CBX store — when an article in this guide says "go to **Products**" or "open **Settings**", it means this CBX menu. ## How CBX appears on your site Your storefront pages (the product list, the configurator, cart, checkout, the customer's account area) are served by the CBX plugin — you don't have to build them. Two things are useful to know: - **CBX keeps WordPress in sync by itself.** For every product list, product and configurator page you create in the CBX menu, the plugin maintains a matching WordPress entry behind the scenes — that is what gives them real addresses on your site (the cart and account area get their own, too). You never edit these entries directly; manage everything in the CBX menu and the pages follow. - **You can also place CBX on any ordinary WordPress page** with the `configbox` shortcode. Paste one of these into the page editor: | Put on the page… | Shortcode | |---|---| | A product list | `[configbox view="productlist" id="1"]` | | One product's configurator | `[configbox view="product" id="12"]` | | A single configurator page | `[configbox view="configuratorpage" id="1"]` | | The cart | `[configbox view="cart"]` | | The checkout | `[configbox view="checkout"]` | | The customer account area | `[configbox view="user"]` | The `id` is the product list's, product's or configurator page's ID — you see it in the respective CBX list screen. Use `configuratorpage` only when you deliberately want one step of a configurator on a page of your own; normally `product` is what you want, because it brings the whole configurator with it. Shortcodes written for older CBX versions keep working: `productlisting` is still accepted as the old spelling of `productlist`. Use `productlist` in anything new. ## What happens next You know where everything lives — from here, the rest of the guide applies unchanged. Continue with [Work the list and edit screens](https://docs.configbox.at/docs/admin-guide/getting-started/the-admin-screens), then build your first product. ## Good to know - **One login, one customer.** Your customers use their normal WordPress accounts; CBX picks the login up automatically — someone who fills a cart as a guest and then logs in keeps their cart. - **Multilingual sites** translate CBX's own texts (product names, questions, answers) in the CBX edit screens — the flag icons next to translatable fields — while your WordPress translation plugin handles the ordinary WP pages around them. - **CBX settings are not under WordPress → Settings.** They live at **CBX → Settings**, inside the CBX menu. - **Command-line tools for your developer or host.** CBX ships maintenance commands for WP-CLI (`wp configbox …`), and a developer can add store-specific ones (an order export for your ERP, say) that appear as `wp configbox custom …`. Nothing you need day to day — just know it exists when your developer asks. For developers → `docs/technical/com_configbox_cli_commands.md`. - **Running WooCommerce as well?** CBX does not feed the WooCommerce cart and checkout — it brings its own, and that is what this guide describes. The two can coexist on one site, but a configured CBX product goes through the CBX checkout. If you need it to reach WooCommerce instead, talk to Rovexo before you plan your store. ## Troubleshooting - **No CBX entry in the admin menu?** Your account lacks the page-editing permission CBX requires, or the CBX plugin is deactivated under **Plugins** — ask your site administrator. - **A page shows the shortcode text instead of the store?** The shortcode sits in a formatted block (a code or quote block) rather than a plain paragraph or a **Shortcode** block — or the CBX plugin is deactivated under **Plugins**. - **The page says `Unknown shortcode`?** The `view` value is misspelled — compare it letter by letter with the table above. - **The page is blank where the store should be?** The `id` points at a record that no longer exists or isn't published. Open the matching CBX list screen and check the ID. --- # Run the setup wizard Page: https://docs.configbox.at/docs/admin-guide/getting-started/run-the-setup-wizard > **Audience:** store admins setting up a new store · **Scope:** the first-run assistant · **Last reviewed:** 2026-07-22 **What this does** — Walks you through the handful of settings CBX needs before you build anything: your licence key, the languages you sell in, your tax basis, your store's identity and your currencies. It runs **once**, the first time you open CBX. Nothing you enter here is permanent — every field has a normal screen elsewhere in the menu, and the wizard tells you which one. Two answers are worth thinking about before you click through, though, because changing them later means revisiting work you have already done: the **languages** you pick and your **base currency**. ## Before you start - Have your **licence key** to hand — it is in your account on the CBX website. - Know which **country** your business operates from and whether you sell mainly **B2B** or **B2C**. If in doubt, read the two bullets in step 3 before choosing. ## Steps The six steps below are what a **Joomla**-hosted store sees. Two hosts see fewer — see the platform note after the last step. 1. **Welcome to CBX** — enter your **License Key** and click **Next**. ![The first wizard step, asking for the licence key](./img/wizard-license.jpeg) 2. **Language settings** — pick the languages your store will run in. CBX offers the languages your site has installed; **Click to see platform languages** expands the list. This is the choice worth pausing on: every language you select adds an input box to **every** translatable field from then on — product titles, question titles, answers, descriptions. Pick the languages you will actually publish, not the ones you might one day want. 3. **Taxes** — set your **Default VAT rate**, the **Country** your company operates from, and whether the store is **B2B or B2C**. ![The taxes step, with the B2B/B2C explanation](./img/wizard-taxes.jpeg) - The **country** matters beyond the rate: pick an EU country and CBX sets the EU VAT rules up for you. - **B2B or B2C** decides how prices are *displayed*, not what is charged: in **B2B**, individual prices and totals are shown **net** with tax listed separately; in **B2C** they are shown **gross** with the included tax stated. US-based businesses are generally fine on B2B for both consumers and companies. - You are choosing a default. Each customer group can override it later — see [Set up customer groups](https://docs.configbox.at/docs/admin-guide/commerce/set-up-customer-groups). - Products with different rates are handled by **tax classes** later, not here. 4. **Store Information** — your **Store Name**, **Store Website** and the **Email for notifications** (where CBX tells you about new orders and reviews). This is the data that ends up on invoices and in emails, so use the legal name and a monitored address. You can refine all of it later under **Store Information** — see [Keep your store information current](https://docs.configbox.at/docs/admin-guide/settings/keep-store-information-current). 5. **Currencies** — define your **base currency** (name, symbol and code), then add any further currencies with their **Rate**. The base currency is the second choice worth pausing on: **every price you type anywhere in CBX is in the base currency**, and other currencies are conversions of it. Changing it after you have priced a catalog means re-checking every price. If you offer more than one currency, make sure the currency selector is placed somewhere visible on your storefront — otherwise customers cannot reach the other currencies. 6. **All done!** — click **To the CBX Dashboard**. > **Platform note:** which steps you get depends on your host. On **WordPress** the **Language > settings** step is skipped — **Next** on the licence step takes you straight to **Taxes**. On > **Magento 2** the wizard stops after **Language settings** and finishes there: taxes, store > information and currencies are Magento's own settings, so CBX does not ask for them — > see [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/). ## What happens next The wizard is marked as completed and will not appear again — from now on, opening CBX takes you straight to the [Dashboard](https://docs.configbox.at/docs/admin-guide/getting-started/check-the-dashboard). Everything you entered is editable in the normal screens: | Set in the wizard | Lives afterwards in | |---|---| | Licence key | **Dashboard** | | Languages | **Settings** | | Default VAT rate, country, B2B/B2C | **Settings**, **Countries**, and per group in **Customers** | | Store name, website, notification email | **Store Information** | | Currencies | **Currencies** | Go on to [Work the list and edit screens](https://docs.configbox.at/docs/admin-guide/getting-started/the-admin-screens), then build your first product. ## Good to know - **The wizard is a shortcut, not a gate.** Skipping a decision now costs nothing; every screen it touches is reachable from the menu. - **Each step is saved as you click Next**, and the wizard only moves forward — there is no Back button. Stopping halfway loses nothing you have already confirmed. - **Languages and base currency are the expensive ones to change.** Everything else is a two-minute edit later. - **The notification email is not the customer-facing address.** It is where *you* get told about orders and reviews; the addresses customers see are configured with the [order emails](https://docs.configbox.at/docs/admin-guide/orders/set-up-order-emails). ## Troubleshooting - **The wizard doesn't appear.** It runs only while the store is unconfigured — once finished, it is done for good. Everything it sets is in the menu screens listed above. - **You left the wizard halfway.** Opening CBX takes you back to it, starting again at step 1 with your saved answers already filled in — click through to the end. - **Your language isn't offered.** CBX lists the languages your *site* has installed. Install the language in your platform first, then add it under **Settings**. - **The licence key is rejected.** Keys are bound to a domain. A staging or development hostname needs to be whitelisted for your key — contact Rovexo with the hostname. --- # Schedule the recurring scripts Page: https://docs.configbox.at/docs/admin-guide/getting-started/schedule-the-recurring-scripts > **Audience:** store owners and whoever administers the site's server · **Scope:** the scheduled > jobs a CBX store needs · **Last reviewed:** 2026-07-29 Almost everything in CBX takes care of itself: routine cleanup runs during normal visits, and nothing needs a nightly job just to keep the store selling. **One script is the exception** — it only works when someone schedules it on the server. ## The AI assistant's journal sweep If you use the **AI Configurator Assistant**, one command needs to run on a schedule: ``` php cli/joomla.php configbox:chatadvisor:analyze ``` Every run does two jobs: - **It enforces the journal retention.** Conversations older than the retention period set in **Settings → AI Configurator Assistant** are deleted. That retention is a promise about visitor data — without the scheduled run, nothing deletes old conversations. - **It writes the lessons-learned reviews.** Conversations that have gone quiet get their AI-written review (visible on each conversation in the journal). This part respects the "Analyze conversations automatically" setting; the retention part runs regardless. - **It maintains the recommendations.** After the reviews, everything newly analysed is folded into the [Recommendations](https://docs.configbox.at/docs/admin-guide/ai-assistant/send-recommendations-to-your-team) backlog — new evidence joins what is already known, genuinely new problems open new entries, and a fixed problem that visitors hit again is flagged as regressed. Without the scheduled run, the backlog only moves when someone presses "Fold them in now" on the screen. Ask whoever administers your server to schedule it — **once per hour** is a good rhythm. A conversation is considered finished after it has been quiet for half an hour, so an hourly run reviews conversations while they are still fresh. If the store does not use the AI assistant, the command does nothing and nothing needs scheduling. ## How to tell that it is running Open **AI Assistant → Conversation Journal** in the CBX menu and look at the **Analyzed** column: with the sweep in place, conversations get their check mark on their own within an hour or two of ending. If older conversations pile up unanalyzed (and never disappear after the retention period), the schedule is not running — the **Analyze** button on each conversation still works by hand in the meantime. --- # Work the list and edit screens Page: https://docs.configbox.at/docs/admin-guide/getting-started/the-admin-screens > **Audience:** store admins · **Scope:** the screen conventions shared across all of CBX · **Last reviewed:** 2026-07-20 **What this does** — Teaches you the two screen types that make up nearly all of CBX. Learn them once and every other article gets shorter: "open the record, change the field, save." ## List screens Open any menu entry (say **Settings → Currencies**, shown here) and you get a list: ![A typical list screen — Currencies](./img/list-example.jpeg) - **Open a record** by clicking its title link (here: *Euro*). - **Add** creates a new record; **Remove** deletes the ones you've ticked. Tick the box in the header row to select everything on the page. - **Active** — the green check in a row toggles the record live/not live directly from the list. Inactive records stay in place but stop appearing on the storefront. - **Sort** by clicking a column heading (where offered). Lists that support manual ordering show a drag handle in an **Ordering** column — drag rows to set the storefront order. - Larger lists (orders, customers, products) add **search boxes and filters** above the table — type or pick, and the list narrows immediately. - Some lists have extra action buttons for their domain — here **Make Default** and **Make Base** act on the ticked currency. They always act on your current selection. - **Copy** (on lists that offer it, e.g. products) duplicates the ticked records with everything attached — the fastest way to create similar things. ## Edit forms Opening or adding a record shows the edit form: ![A typical edit form — a currency](./img/edit-example.jpeg) - The buttons sit at the top right: **Save** (stay on the form), **Save and Close** (back to the list), **Cancel** (discard), **Help**. Nothing is stored until you save. - **Required fields** are marked with a red label and `*`. Saving with one empty highlights it. - **Yes/No choices** render as two tick boxes — exactly one is active. - Long forms (products, questions, the Settings screen) group fields into **collapsible sections** — click a section heading to open or close it. If you don't see a field an article mentions, its section is probably folded shut. ## Translatable fields and languages Fields your customers see (titles, descriptions, labels) exist **once per active shop language**, side by side — in the screenshot above: **Title - English** and **Title - German**. Fill each language; what a customer sees follows the language they browse in. Which languages appear here is set by the **Active Languages** in **Settings** — adding a language there adds a column to every translatable field in the store. ## Good to know - **Deleting is guarded.** CBX blocks deleting records that other things still depend on (e.g. an answer referenced by a rule) and tells you what's in the way — deactivate instead if you just want something off the storefront. - **Inactive ≠ deleted.** Unpublishing a product, page, question or answer hides it from customers but keeps everything (including its role in old orders) intact. - Numeric fields follow your shop's decimal convention — enter prices the way the form shows them. --- # CBX on Magento 2 Page: https://docs.configbox.at/docs/admin-guide/magento2/ > **Audience:** store admins on Magento 2 · **Scope:** what is different on Magento, and which parts of this guide apply · **Last reviewed:** 2026-07-25 **TL;DR** — On Magento 2, CBX is the **configurator**; **Magento is the shop**. You build products, questions, rules and prices in CBX and attach them to your Magento catalog products — cart, checkout, orders, customers, emails, taxes, shipping and payment are all handled by Magento, exactly as for any other Magento product. Roughly half of this guide therefore isn't for you; this page tells you which half, so you never go looking for a screen that isn't there. ## Articles 1. **[Connect a CBX product to a Magento product](https://docs.configbox.at/docs/admin-guide/magento2/connect-a-magento-product)** — the one Magento-specific task: making a catalog product configurable. ## Who does what — the one table to internalize | Job | Done in | Where | |---|---|---| | Building the configurator — products, pages, questions, answers, rules, prices, visual preview | **CBX** | **Configbox → Administration** in the Magento admin | | Product catalog, listings, product pages | **Magento** | **Catalog → Products** | | Cart & checkout | **Magento** | the standard Magento storefront | | Orders, invoices, shipments, credit memos | **Magento** | **Sales → Orders** | | Customers and accounts | **Magento** | **Customers** | | All customer emails (order confirmations etc.) | **Magento** | Magento's transactional emails — CBX sends **no** email here | | Taxes | **Magento** | tax classes/rules on the Magento product; configurator prices follow them | | Currencies, price display, languages | **Magento** | store configuration and store views | | Shipping & payment methods | **Magento** | Magento's shipping/payment setup | | Discounts & promotions | **Magento** | cart price rules, applied on top of the configured price | ## Your CBX menu is shorter — that's normal You reach CBX through the **Configbox** entry in the Magento admin sidebar — its single item, **Administration**, opens the complete CBX admin: ![The Configbox entry in the Magento admin menu](img/magento-menu-configbox.jpeg) Because Magento owns the shop, the CBX menu on Magento shows only four entries: **Dashboard, Products, Calculations, Settings**. Everything else this guide's [getting-started menu tour](https://docs.configbox.at/docs/admin-guide/getting-started/) lists — Orders, Customers, Reviews, Product Lists, Countries, Shipping, Payment Methods, Store Information, Customer Fields, Notifications — is deliberately hidden, because those jobs are done in the corresponding Magento screens (table above). Nothing is broken and nothing needs enabling. ![The CBX admin inside Magento, with its four-entry menu](img/configbox-admin-dashboard.jpeg) ## Which parts of this guide apply to you | System | On Magento 2 | |---|---| | [Getting started](https://docs.configbox.at/docs/admin-guide/getting-started/) | **Read it** — the list/edit screen conventions and the dashboard work the same. Skip the menu entries your menu doesn't show. | | [Products & configurator](https://docs.configbox.at/docs/admin-guide/products/) | **Fully applies** — this is your main manual. (Exception: *product lists* — Magento's catalog does that job.) | | [Rules — conditional logic](https://docs.configbox.at/docs/admin-guide/rules/) | **Fully applies.** | | [Pricing & calculations](https://docs.configbox.at/docs/admin-guide/pricing/) | **Fully applies** for building prices. Taxes and currency come from Magento, not from CBX screens. | | [Customers, taxes, shipping & payment](https://docs.configbox.at/docs/admin-guide/commerce/) | **Skip it** — all of it is Magento's job. | | [Orders & daily operations](https://docs.configbox.at/docs/admin-guide/orders/) | **Skip it** — orders, customers, reviews and emails are Magento's. There are no order records inside CBX on Magento. | | [Store settings](https://docs.configbox.at/docs/admin-guide/settings/) | **Partly applies** — the Settings screen exists, but its commerce/checkout sections (and Store Information / Customer Fields) are hidden on Magento. | ## Where the configured product shows up When a customer configures a product and adds it to the cart, the Magento cart line shows the selected answers as the item's option value, priced at the CBX-calculated price. ![A Magento cart line showing the configured answers under Configuration, at the CBX-calculated price](img/magento-cart-line.jpeg) The Magento **order** carries the same selection summary plus the answer **SKUs** on the line item — that is what fulfilment works from. From cart onward, everything (checkout, order status, invoices, emails, refunds) is standard Magento — note the tax, shipping and totals above are all Magento's, computed from the configured price. ## Good to know - **CBX settings are not under Stores → Configuration.** They live in **Configbox → Administration → Settings** — Magento's system configuration has no CBX section on purpose. - **Don't look for orders inside CBX.** The Orders screen doesn't exist on Magento; use **Sales → Orders**. - **CBX sends no email on Magento.** If an article mentions notification emails, that's the other platforms — here, Magento's emails cover the order flow. - **Quotations, saved carts, CBX customer accounts and CBX reviews** are part of CBX's own checkout on other platforms and are **not available** on Magento — use Magento equivalents where they exist. - **One CBX configuration per Magento product.** A Magento product can carry exactly one CBX product link (see [connecting products](https://docs.configbox.at/docs/admin-guide/magento2/connect-a-magento-product)). For developers and integrators (installation, command line, technical behavior) → `docs/platform/magento2/com_configbox_magento2_platform_guide.md` --- # Connect a CBX product to a Magento product Page: https://docs.configbox.at/docs/admin-guide/magento2/connect-a-magento-product > **Audience:** store admins on Magento 2 · **Scope:** making one Magento catalog product configurable · **Last reviewed:** 2026-07-25 **What this does** — Puts the CBX configurator on a Magento product's storefront page. The customer configures right on the product page and adds the result to the normal Magento cart. ## Before you start - Build the CBX product first — pages, questions, answers, rules, prices — in **Configbox → Administration → Products** (see [Products & configurator](https://docs.configbox.at/docs/admin-guide/products/)). You can refine it later; the link doesn't need rebuilding after changes. - Have the Magento catalog product ready (or create it now) — a simple product is the usual choice. Its Magento price is what a customer pays *without* configuring; the configured price replaces it in the cart. ## Steps 1. In the Magento admin, open **Catalog → Products** and edit the product. 2. Scroll to **Customizable Options** and click **Add Option**. 3. Set the new option's type to **CBX Configuration** (in the **Rovexo** group of the type dropdown). 4. In the **Select Configbox Product to Associate** dropdown that appears, pick the CBX product to attach. 5. **Save** the product. ![A product's custom option of type CBX Configuration](img/magento-product-custom-option.jpeg) ## What happens next The configurator renders automatically on that product's storefront page — the questions in the product-options area, the visual preview in the image/gallery area. There is nothing to place, no widget and no page edit: the custom option is the only attachment point, and it is enough. ![The storefront product page with the CBX configurator in the product-options area and the visual preview in the gallery](img/magento-storefront-configurator.jpeg) The price above the questions is the CBX-calculated total, updated live as the customer chooses; **Add to Cart** is Magento's own button, unchanged. ## Good to know - **One CBX configuration per Magento product.** The link supports exactly one CBX product; adding a second CBX-type option is not supported and silently keeps only one. To offer two configurable products, use two Magento products. - **Duplicating the Magento product keeps the link** — the copy points at the same CBX product. - **Prices and tax follow Magento.** The configured price is calculated by CBX but taxed by the Magento product's tax class, so the storefront price display matches the rest of your store. - **The same CBX product can be attached to several Magento products** — for example one configurator behind several catalog entries per store view. ## Troubleshooting - **No "CBX Configuration" type in the dropdown** — the CBX module isn't (fully) installed on this Magento instance; ask whoever maintains the site. - **The configurator doesn't appear on the product page** — check the option was saved with a CBX product selected, and that the CBX product is published (see [add a product](https://docs.configbox.at/docs/admin-guide/products/add-a-product)). --- # Orders & daily operations Page: https://docs.configbox.at/docs/admin-guide/orders/ > **Audience:** store admins, back-office staff · **Scope:** running the store once customers use it · **Last reviewed:** 2026-07-20 **TL;DR** — Orders arrive as **frozen snapshots** — you don't edit their content, you move them through a **status lifecycle** (Ordered → Paid → Confirmed → Shipped …). Status changes trigger the **notification emails**; invoices and manufacturing slips generate from the order screen. Alongside orders you manage **customer records** and moderate **reviews**. > **Platform note (Magento 2):** this whole system does **not apply** on Magento-hosted stores — > orders, customers, reviews and all emails are Magento's, and CBX keeps no order records > there (the screens described here are hidden). See > [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/). ## Articles 1. **[Process an order](https://docs.configbox.at/docs/admin-guide/orders/process-an-order)** — find it, read it, change its status, produce invoice and manufacturing slip. 2. **[Set up the order emails](https://docs.configbox.at/docs/admin-guide/orders/set-up-order-emails)** — the status-triggered templates and their placeholders. 3. **[Manage customers](https://docs.configbox.at/docs/admin-guide/orders/manage-customers)** — addresses, VAT numbers, group membership, guest accounts. 4. **[Moderate reviews](https://docs.configbox.at/docs/admin-guide/orders/moderate-reviews)** — the approval queue for product reviews. 5. **[Handle quotations and saved carts](https://docs.configbox.at/docs/admin-guide/orders/quotations-and-saved-carts)** — the non-purchase flows: Request Quote and Save Cart, and how they land in Orders. ## The screens - **Orders** — every order, quotation and saved cart, with customer search, date and status filters: ![The Orders list](./img/orders-list.jpeg) - **Customers** — the customer records behind orders: billing/delivery addresses, VAT number, customer group, language, newsletter opt-in. - **Reviews** — the moderation queue; new reviews arrive unpublished and go live when you activate them. - **Notifications** — the status-triggered email templates (to the customer and/or the shop manager, with placeholders for order and customer data). ## The status lifecycle | Status | Meaning | |---|---| | Not ordered / In Checkout | a cart that hasn't been submitted (yet) | | **Ordered** | placed, awaiting payment | | **Paid** | payment received (Incorrect amount paid flags a mismatch) | | **Confirmed** | accepted by you | | **Shipped** | dispatched | | Cancelled / Refunded | terminated | | Saved | a saved-for-later cart | | Quotation requested / Quotation sent | the request-a-quote flow | Each status change can fire its matching notification email — which is why you drive orders by status instead of emailing manually. --- # Manage customers Page: https://docs.configbox.at/docs/admin-guide/orders/manage-customers > **Audience:** store admins, back-office staff · **Scope:** the Customers screen · **Last reviewed:** 2026-07-20 **What this does** — The customer record is the account behind orders: addresses, contact data, VAT number, language, and — commercially decisive — the **customer group**. Here you fix typos, upgrade someone to the trade group, or link a store customer to their site login. ## Steps 1. Go to **Customers** and open a record (the orders list links here from each order too): ![The customer form](./img/customer-edit.jpeg) 2. What you'll actually edit: - **Billing Address** — company, salutation, name, address, country/state, email, phone. - **Delivery Address** — a separate block; **Same as billing** collapses it. - **VAT IN** — the VAT number; for EU B2B customers this drives reverse-charge handling, so fixing a wrong one matters. - **Customer group** — move the customer between segments; their pricing mode, permissions and discounts change with it (see [customer groups](https://docs.configbox.at/docs/admin-guide/commerce/set-up-customer-groups)). - **Language** and **Newsletter** — communication preferences; notifications use the customer's language. - **Platform User ID** — the linked site account; this link is how a login lands on this customer record (and in the group its platform group maps to). 3. **Save**. ## What happens next Changes apply to the account and to **future** orders. Placed orders keep the address data they were ordered with — that's deliberate (the order is the historical record); the order screen links back here for the current data. ## Good to know - **Guest checkouts** create temporary records ("No customer account" rows in the orders list are their earliest stage). Completed purchases become permanent customers; abandoned temporaries are pruned automatically after the lifetime set in **Settings → Maintenance**. - Which fields customers themselves see and must fill (checkout, quotation, profile) is the [Customer Fields matrix](https://docs.configbox.at/docs/admin-guide/settings/tailor-the-customer-fields) — not this screen. - The **custom fields** at the bottom are free-form slots (labels from **Settings**) — usable for internal notes like a CRM id, and readable by rules. --- # Moderate reviews Page: https://docs.configbox.at/docs/admin-guide/orders/moderate-reviews > **Audience:** store admins · **Scope:** the Reviews screen · **Last reviewed:** 2026-07-20 **What this does** — Customer reviews go through you before the world sees them: new submissions arrive **unpublished**, and nothing shows on the storefront until you activate it. ## Before you start - Reviews must be enabled: **Settings → Reviews → Reviews for Products**, and the product's own **Enable Reviews** switch. Set the **review notification email address** there too, so new submissions alert you instead of waiting to be discovered. ## Steps 1. Go to **Reviews**: ![The Reviews list](./img/reviews.jpeg) 2. Unpublished rows are the queue. Open one to read the **name**, star **rating**, **comment**, **product** and **language**. 3. Then either: - **Approve** — set it **Active** (from the form, or the check in the list row). It appears on the product immediately and counts into the star average. - **Edit first** — trim personal data or fix formatting, then activate. Keep edits light; a review is the customer's voice. - **Remove** — delete spam or abuse. ## What happens next Active reviews show on the product's detail page (per language) with their stars; the aggregate rating appears on listing tiles. Deactivating a review later removes it from the storefront but keeps it in the list. ## Good to know - Reviews are **per language** — a review shows to storefront visitors browsing its language. - Currently any visitor can submit a review — purchase-verified reviewing is a known product gap, so moderation here is your quality gate; check the reviewer name against [customers](https://docs.configbox.at/docs/admin-guide/orders/manage-customers)/orders when authenticity matters. - No reviews showing at all despite active ones? Check the two enable switches (global and per-product) before suspecting the reviews themselves. --- # Process an order Page: https://docs.configbox.at/docs/admin-guide/orders/process-an-order > **Audience:** back-office staff · **Scope:** one order, from arrival to shipped · **Last reviewed:** 2026-07-20 **What this does** — Walks the everyday order routine: open the order, check what was bought, move it through its statuses (which sends the emails), and generate the paperwork. ## Before you start - Know your store's **invoicing mode** (set in **Settings**): invoices generate automatically on order, automatically once payment is cleared, or only when you upload one — it decides which invoice actions you'll see on the order. ## Steps 1. Go to **Orders**. Narrow the list with the **customer search**, the two **date filters** or the **status** dropdown, and click the order's **Display** link. 2. Read the order: ![An order's detail screen](./img/order-detail.jpeg) - **Ordered Products** — each position with quantity and price; **Details** unfolds the full configuration of that position, exactly as the customer built it. - Below the positions: the subtotal, the **delivery** method and cost, the **payment method** and any surcharge, and the **total including tax**. Tax notes (e.g. the reverse-charge line for VAT-free B2B orders) appear here too. - The customer's billing and delivery addresses are shown as placed — an order is a frozen snapshot, so later catalog or account changes never alter it. (Correct account data on the customer record instead; the order keeps its own copy.) 3. Drive it forward in the **Status** panel: pick the new status and click **Update**. Typical path: **Ordered → Paid → Confirmed → Shipped** — payment providers with instant confirmation set *Paid* automatically; for bank transfer you set it yourself when the money arrives. Each change can fire the matching **notification** email to customer and shop manager. 4. Paperwork: - **Invoice** — depending on the invoicing mode: download the generated invoice, generate & release it after clearance, or upload your own PDF. Released invoices can also be emailed automatically (a **Settings** switch). - **Manufacturing Slip → Download** — the production/packing PDF for the workshop: every position with its full configuration, printable on demand. ## What happens next The customer sees status progress in the emails you trigger; production works from the slip; the order stays as the permanent record of exactly what was sold at what price. ## Good to know - **Quotations and saved carts** live in the same list (statuses *Quotation requested*, *Quotation sent*, *Saved*) — the quote flow issues a quotation PDF rather than an invoice. - **Cancelling/refunding** is a status change too — with its own notification templates. - If an expected email didn't go out, check **Notifications**: there must be an active template tied to that status with "send" enabled. - Rows with **"No customer account"** are guest checkouts mid-flow; abandoned ones are cleaned up automatically after the lifetime set in **Settings → Maintenance**. --- # Handle quotations and saved carts Page: https://docs.configbox.at/docs/admin-guide/orders/quotations-and-saved-carts > **Audience:** store admins, back-office staff · **Scope:** the quotation and saved-cart flows · **Last reviewed:** 2026-07-23 **What this does** — Not every configured cart is a purchase. CBX gives customers two non-buying exits from the cart — **Request Quote** and **Save Cart** — and both land in the same **Orders** list as real orders, with their own statuses, so you can follow them up. ## The two flows, from the storefront Besides **Checkout**, the cart offers **Save Cart** and **Request Quote**: - **Save Cart** — the customer gives a name and email, and the cart is stored. It reappears in their account under **Order History** with status **Saved**, ready to reopen and finish later. - **Request Quote** — opens the **Get a quotation** address form; after **Get Quote** the customer reaches a "Thank you, your quotation is ready to download" page with a **Download** button. The request arrives in **Orders** with status **Quotation requested**, and becomes **Quotation sent** once you issue the quote. Neither is a purchase: no payment is taken, and nothing ships until the customer comes back and checks out (or you convert the quote). ## Finding them in the back office Open **Orders** in the CBX menu. Quotations and saved carts sit in the same list as orders: ![The Orders list showing Saved and Quotation-sent rows](img/quotations-saved-carts.jpeg) The list shows **ID**, **Order** (its **Display** link), **Customer**, **Status** and **Time Created**. Narrow it with **Search for Customer**, the two date filters, or the **Select Status** dropdown — pick a quotation or saved status to see only those. Here, customer "Demo Alex" has a **Saved** cart and a **Quotation sent**. ## Following up - **A quotation:** open it with **Display**, review what was configured, and issue the quote — the flow produces a **quotation PDF** (not an invoice). Sending it moves the status to **Quotation sent**; if the customer accepts, they proceed to a normal order. - **A saved cart:** it's the customer's to resume from their account — you mostly leave it be, but it's visible here so you can see demand that hasn't converted yet. ## Good to know - These share the [order status lifecycle](https://docs.configbox.at/docs/admin-guide/orders/); a status change can fire its **notification** email, same as for orders — see [set up the order emails](https://docs.configbox.at/docs/admin-guide/orders/set-up-order-emails). - The everyday order routine — reading positions, driving status, invoices, manufacturing slips — is in [process an order](https://docs.configbox.at/docs/admin-guide/orders/process-an-order); this article is only the non-purchase side. - Abandoned guest saved carts and quotations are cleaned up automatically after the lifetime set in **Settings → Maintenance**; give real prospects an account so their records persist. --- # Set up the order emails Page: https://docs.configbox.at/docs/admin-guide/orders/set-up-order-emails > **Audience:** store admins · **Scope:** the Notifications screen · **Last reviewed:** 2026-07-20 **What this does** — Notifications are the emails your store sends by itself as orders change status: order received, payment confirmed, shipped, quotation ready … Each template is tied to **one order status** and can address the **customer**, the **shop manager**, or both. Set these up once, and [processing an order](https://docs.configbox.at/docs/admin-guide/orders/process-an-order) becomes "change the status — the email takes care of itself". ## Steps 1. Go to **Notifications** and open a template (or **Add** one): ![A notification template](./img/notification-edit.jpeg) 2. The header fields: - **Name** — back-office label ("Payment Confirmation"). - **Status Code** — the order status that fires this template (here: **Paid**). One template per status you want to communicate. 3. The **E-Mail to Customer** section: - **Send email** — the on/off switch for this recipient. - **Subject** — per language. - **Email HTML** — the body, per language, in a rich-text editor. Write it like a normal email and drop in **placeholders** where order data belongs — the demo template reads: > Dear `{firstname}` `{lastname}`! We have received your payment for order id > `{order_id}` and will ship as soon as possible. … Kind regards, `{shopname}` Placeholders are replaced per order at send time — customer fields, order data, and your [store information](https://docs.configbox.at/docs/admin-guide/settings/keep-store-information-current) (`{shopname}` etc.). 4. The **E-Mail to Shop Manager** section works identically — its own switch, subject and body. Use it for internal alerts ("New order {order_id} needs confirmation"). 5. **Save**, then test: place a test order and move it through the statuses — every email should arrive, in the right language, with every placeholder filled. ## What happens next From now on, each status change on an order fires its matching active template automatically — whether the status was set by a payment provider (→ *Paid*) or by you in the order screen. ## Good to know - **No email went out?** Check, in order: does a template exist for that exact status · is its **Send email** on · is the template's language content filled for the customer's language. - The **quotation** flow has its own statuses (*Quotation requested*, *Quotation sent*) — give them templates too, or quote customers hear nothing. Whether the quote PDF is attached is a [customer-group switch](https://docs.configbox.at/docs/admin-guide/commerce/set-up-customer-groups). - Invoices can be emailed automatically when released — that's the **Send invoice via email** switch in **Settings → Invoicing**, separate from these templates. - Keep bodies short and factual; the order details are in the customer's account and on the attached documents. A subject like "Your order {order_id} has shipped" beats prose. --- # Track payments Page: https://docs.configbox.at/docs/admin-guide/orders/track-payments > **Audience:** store admins · **Scope:** the Payments screen and the customer's payment pages · **Last reviewed:** 2026-08-15 **What this does** — Every payment attempt a customer makes is recorded, whatever its fate: paid, declined, abandoned, still pending. The **Payments** screen shows them all, tells the full story of each, and is where you settle payments that arrive outside the provider — bank transfers above all. ## Reading the list ![The payments ledger](./img/payments-ledger.jpeg) Open **Payments** in the ConfigBox menu. Each row is one payment attempt: its order, provider, amount, state and when it last changed. Filter by state, provider, test/live or date to find what you need. An order the customer retried appears once per attempt — that is intentional; the failed attempt stays visible next to the successful one. The states in plain words: | State | Meaning | |---|---| | Pending | Started; the outcome is not known yet — normal for bank transfers and slow methods | | Settled | The money is confirmed; the order flipped to *Paid* | | Failed | Declined or errored — the customer was offered a retry | | Canceled | The customer backed out on the provider's page | | Expired | Never finished and timed out at the provider | ## The payment detail Click a row to see everything about that payment: the facts (amounts, references at the provider, test or live) and the **timeline** — every step from creation through provider responses to the final state, including calls the provider made to your store. When something looks wrong, the timeline is where you find out what actually happened; nothing about a payment lives only in a log file. Three buttons act on a payment: - **Mark as settled** — for money that arrives outside the provider: you saw the bank transfer on your statement, so the payment settles and the order flips to *Paid*. The timeline records that you did this, and when. - **Mark as failed** — writes off an attempt you know is dead. - **Check with provider** — asks the provider for the current status right now, for providers that support it. The store also does this on its own for pending payments, so this button is for impatience, not necessity. ## What the customer sees After paying, the customer lands on one of three pages with stable, readable addresses — handy if you track conversion funnels: - **Thank you** (`/thank-you/`) — the payment is confirmed. - **Payment pending** (`/payment-pending/`) — nothing is wrong; the confirmation just has not arrived yet. For bank transfers this page shows your account details, the payment reference and (for Swiss QR-bill) the scannable QR code. The page watches for the confirmation and forwards itself to the thank-you page the moment it arrives. - **Payment failed** (`/payment-failed/`) — with a button that reopens the checkout exactly as the customer left it, so they can retry or switch to another payment method. These pages never lie: opening the thank-you address of an unpaid order redirects to the honest one. ## Good to know - **Orders are never marked *Paid* automatically at placement.** An order waits on *Awaiting payment* until its payment settles — through the provider's confirmation, a re-check, or your **Mark as settled**. - If a provider reports a different amount than the order expects, the payment fails and the order is set to *Incorrect amount paid* rather than silently accepting the difference. - **Recent events** (in the Payments screen) lists the last provider calls across all payments — the place to look when a provider claims "we notified your store". - Test payments are marked as such in the list; filter them out when reconciling real money. --- # Pricing & calculations Page: https://docs.configbox.at/docs/admin-guide/pricing/ > **Audience:** store admins · **Scope:** everything that determines a configured product's price · **Last reviewed:** 2026-07-25 **TL;DR** — Simple pricing needs no formulas at all: a product **base price** plus a static **price per answer**. When a price must *depend* on the configuration — area pricing, bracketed rates, quantity effects — you build a **calculation** (a named, product-scoped formula) and attach it to a question or answer. The customer always sees the resulting price live. > **Platform note (Magento 2):** building prices **fully applies** on Magento-hosted stores, but > **taxes and currencies come from Magento**, not from CBX screens — the configured price is > calculated here and taxed by the Magento product's tax class. See > [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/). ## What can you build? The three calculation styles cover just about any pricing scheme a configurable product needs — and they compose, so one calculation can feed another: - **Area & measure pricing** — price from what the customer types. The formula below charges €89/m² from the entered width and height, rounded to cents — built entirely by drag-and-drop: ![An area-price formula: Round((Width × Height) / 1,000,000 × 89, 2)](./img/calculation-formula.jpeg) - **Bracketed price tables** — a matrix looks a price up from two inputs (question entries, selections or other calculations), with exact or next-higher/next-lower bracket matching — and you can paste the whole grid from a spreadsheet: ![A filled Width × Height price matrix with next-higher brackets](./img/calculation-matrix.jpeg) - **Typed expressions** — the Code style for when logic beats dragging: conditions, thresholds, and the results of other calculations in one line (here: 5% off the glazing price for builds from 4 m width): ![A code expression chaining another calculation](./img/calculation-code.jpeg) - Plus **quantity effects**, **per-customer-group math**, **recurring prices** and **weight-driven shipping** — each covered in its article below. ## Articles 1. **[Where prices come from](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from)** — the pricing building blocks and how they add up; read this before creating any calculation. 2. **[Build a calculation](https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation)** — the Formula editor, plus when to use the Code and Matrix styles instead. 3. **[Price with a matrix](https://docs.configbox.at/docs/admin-guide/pricing/price-with-a-matrix)** — the lookup table in depth: axes, brackets, spreadsheet import and multipliers. 4. **[Write a code expression](https://docs.configbox.at/docs/admin-guide/pricing/write-a-code-expression)** — the typed style: placeholders A–D, the full keyword reference and worked examples. 5. **[Charge recurring (subscription) prices](https://docs.configbox.at/docs/admin-guide/pricing/recurring-pricing)** — bill an answer or the product on a repeating cycle alongside the one-off price. 6. **[Set product weight for shipping](https://docs.configbox.at/docs/admin-guide/pricing/weight-and-shipping-weight)** — the per-answer and product weight that weight-based shipping prices delivery from. ## The three calculation styles Created under **Calculations** (each belongs to one product): | Style | You author | Best for | |---|---|---| | **Formula** | drag-and-drop terms: numbers, question entries, other calculations, functions | readable arithmetic — most pricing | | **Code** | a typed expression with placeholders and macros | quick math, totals-based surcharges | | **Matrix** | a 2-D lookup table (importable from Excel) | "price depends on two inputs" tables | All three produce a number from the current selections. You author in the **base currency** and ignore tax — currency conversion, customer-group overrides and tax are applied automatically on top of the result. --- # Build a calculation Page: https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation > **Audience:** store admins · **Scope:** creating a calculation and attaching it · **Last reviewed:** 2026-07-20 **What this does** — Creates a named formula that turns the customer's current selections into a number, and wires it into a price (or weight, or an input bound). Example built below: an area price — *entry in Width × entry in Height × 0.20*. ## Before you start - Read [where prices come from](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from) so the calculation lands in the right place. - The questions the formula reads must exist. ## Steps 1. Go to **Calculations**, click **Add**, name the calculation (you'll pick it by this name later), choose the **product** it belongs to and the style **Formula**. 2. Build the expression in the editor: ![The formula editor with an area-price formula](./img/calculation-formula.jpeg) - Drag **Calculation Terms** into the Calculation area: the arithmetic chips (**+ − * /**), a **Number** chip (type its value, e.g. `0.20`), and terms from the tabs: - **Questions** — pick a question to drag in its **Entry** (what the customer entered/selected), its **price**, or its custom fields. Each question term has a small **"or …"** box — the fallback value used while the question has no entry yet; set it (usually `0` or `1`) so the price never shows blank. - **Calculations** — the result of another calculation of this product; this is how you compose small readable pieces instead of one monster formula. - **Customer** — values from the customer's group, for segment-dependent math. - **Functions** — **Round**, **Lowest value**, **Highest value** (and any store-specific extras): each parameter is a slot you drop further terms into. - Arrange chips left-to-right; normal arithmetic precedence applies, and **Put in parentheses** groups selected chips. **Remove selected** deletes; **Limit term width** compacts long chips. 3. **Save**. 4. Attach it — nothing happens until you do: - Open the question (or answer) → **Calculations** section → pick the calculation as its **Price Calculation** (or Recurring Price / Weight Calculation), or - use it as a **Calculated Minimum/Maximum Value** on a numeric question, or - reference it from a [rule](https://docs.configbox.at/docs/admin-guide/rules/build-a-rule) ("Results of calculations") or from another calculation. ![The whole question form, with the Calculations section's price and weight assignments highlighted](./img/attach-calculation.jpeg) 5. Check it live: open the configurator, change the inputs, watch the price move. ## The special "Regarding Question" term In the Questions tab, **Regarding Question** means "whatever question this calculation is attached to". A calculation built with it (e.g. `Entry in Regarding Question × 2.5`) can be attached to many questions at once and always reads *its own* question — one formula instead of ten near-copies. ## When Formula isn't the right style - **Code** — a typed expression, faster for totals-based math ("12% of the running total") and for formulas easier typed than dragged: bind questions to placeholders `A`–`D` and write `A * B / 1000000 * 65`. Keywords give access to totals, question entries/prices and other calculations. → **[Write a code expression](https://docs.configbox.at/docs/admin-guide/pricing/write-a-code-expression)** - **Matrix** — a lookup table when pricing *is* a table: choose what keys the **rows** and **columns** (a question's value or a calculation's result), fill the grid (or import an Excel file), and pick the matching mode — exact value, or round up/down to the **next bracket**. Multipliers can scale the looked-up cell by a quantity question or another calculation. → **[Price with a matrix](https://docs.configbox.at/docs/admin-guide/pricing/price-with-a-matrix)** All three styles attach identically (step 4) and can reference each other. ## Good to know - **Compose, don't inflate**: several small named calculations referencing each other stay debuggable; one giant formula doesn't. - Calculations recompute on **every selection change** — very deep chains can slow the configurator. - The calculation edit form lists **where it is in use** — check before changing shared pieces. - Copying a product copies its calculations and re-points every reference automatically. - Author in the **base currency**; never bake tax or currency conversion into a formula. --- # Price with a lookup matrix Page: https://docs.configbox.at/docs/admin-guide/pricing/price-with-a-matrix > **Audience:** store admins · **Scope:** the Matrix calculation style · **Last reviewed:** 2026-07-21 **What this does** — Turns a price table you already have — a supplier price list, a size grid, a quantity-discount ladder — into a working price, without writing a single formula. You choose what the **rows** and the **columns** stand for, fill in the cells, and CBX looks up the cell that matches the customer's configuration. Reach for a matrix whenever pricing *is* a table. Trying to express a price table as arithmetic is where formulas turn unreadable. ## Before you start - Read [where prices come from](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from) and [build a calculation](https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation) — a matrix is one of the three calculation styles and is created, saved and attached exactly like the others. - Decide the **two inputs** that drive the price, and have the questions they come from already built. A matrix can use one input or two — never more. - Have your price table to hand. If it lives in Excel, keep it open: you can import it. ## Steps 1. Go to **Calculations**, click **Add**, name the calculation, choose the **product** and pick the style **Matrix**. 2. **Say what the rows and columns stand for.** Above and to the left of the grid, each axis shows its current setting followed by a **change** link. Hover **change** to open the axis picker: ![The axis picker, with the Questions and Calculations tabs](img/matrix-axis-picker.jpeg) - **Questions** — pick a question. This is the usual choice. - **Calculations** — use the *result* of another calculation of this product as the axis. Use this when the real driver is computed rather than entered (area, total weight, running total). - **Ignore this input** — collapse that axis. A matrix with one axis ignored becomes a simple one-dimensional lookup list. The axis label then tells you what CBX will read: | Label | What it means | |---|---| | **Entry in ``** | The number the customer typed — the grid headers are numbers you fill in | | **Selection for ``** | The answer the customer picked — the grid headers become answer drop-downs | | **Result of calculation ``** | The value another calculation produced | | **Ignored** | This axis isn't used | You cannot mix the two within one axis — an axis is either a question, a calculation, or ignored. 3. **Fill the grid.** Type the price into each cell. The blue **+** button to the right of the grid adds a column; the one below adds a row. ![The matrix grid: entered widths down the side, heights across the top, and a price in every cell](img/calculation-matrix.jpeg) The **gear** icon in the grid's top-left corner shows the edit icons — drag handles for reordering rows and columns, and an **×** on each header to delete it. Grey header cells are the *parameters* (the values looked up); white cells are the *results*. Write numbers with a **dot** as the decimal mark and no thousands separators. 4. **Or import the table from a spreadsheet.** Click **Import from a spreadsheet** and pick an `.xls` or `.xlsx` file. The first row and the first column go into the grey parameter cells — except on an axis whose question has predefined answers, where the parameters come from the answers themselves and the file's first row/column is ignored. Everything else fills the value cells. Importing **replaces** the whole grid, so import before hand-editing, not after. 5. **Set the lookup behaviour** under **Advanced Settings** (collapsed by default): ![The matrix Advanced Settings, expanded](img/matrix-advanced-settings.jpeg) | Setting | What it does | |---|---| | **Lookup Value** | What to do when the customer's value falls *between* two rows/columns — **Exact Value**, **Next higher value** (the default) or **Next lower value** | | **Round Values to** | Rounds the customer's value up before looking it up — `1` to whole numbers, `10` to full tens, and so on. **Only applies when Lookup Value is Exact Value** | | **Multiplier** | Multiplies the looked-up cell by a fixed number — the usual way to enter supplier prices and add your margin on top | | **Question Selection Multiplier** | Multiplies the result by the customer's entry in a question you pick — how you turn a per-unit table into a line total | | **Calculated multiplier** | Same idea, but the multiplier is another calculation's result | 6. **Save**, then **attach it** — a calculation does nothing until it is used. Open the question or answer → **Calculations** → set it as the **Price Calculation** (or Recurring Price / Weight Calculation), or reference it from a rule or another calculation. See [build a calculation](https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation) for the attachment step in full. 7. Open the configurator and change both inputs. Watch the price step from bracket to bracket. ## How a value is looked up For each axis, CBX takes the customer's value and finds the matching header: - an **exact** header match always wins; - otherwise **Lookup Value** decides which neighbour to use. Take a width table with columns `10, 20, 30, 40, 50` and a customer who enters **25**: | Lookup Value | Column used | |---|---| | Next higher value | `30` — the customer never pays less than the bracket they fall into | | Next lower value | `20` — the customer keeps the cheaper bracket they have reached | | Exact Value | none — unless **Round Values to** brings 25 onto a header first | Then the same happens on the other axis, and the cell where the chosen row and column meet is the result — multiplied by any multipliers you set. **Values outside the table** clamp to the nearest edge: an entry below the first header uses the first, an entry above the last uses the last. Give your table a top row that is deliberately generous, or add a rule that stops the customer going past it. ## Recipes **Quantity discount ladder.** Rows = the quantity question, columns = ignored (or a variant question). Fill the rows with the discount or unit price that applies *from* that quantity onward, and set **Lookup Value** to **Next lower value** — a customer ordering 700 keeps the 500 rate until they reach 1000. That is exactly how the demo store's *Discount by copies* matrix works. **Size grid.** Rows = the height question, columns = the width question, cells = the finished price. Set **Lookup Value** to **Next higher value** so an in-between size is charged at the next size up. **Answer × answer grid.** Both axes are questions with predefined answers (material × finish, for example). The headers become answer drop-downs, no numbers involved, and every combination gets its own price. **Supplier list with margin.** Import the supplier's spreadsheet untouched and put your markup in **Multiplier** (`1.35` for 35%). When the supplier sends a new list, re-import and the margin survives. **Per-unit table.** Keep the table as a *unit* price and set **Question Selection Multiplier** to the quantity question, rather than baking quantity into the grid. ## Good to know - A matrix is **product-scoped**, like every calculation. Copying the product copies its matrices and re-points the references. - Grey parameter cells accept numbers only, on a numeric axis. If you need text keys, drive that axis from a question with predefined answers instead. - Keep tables **sorted** — the drag handles under the gear icon exist for exactly this. An out-of-order table still looks up correctly, but it becomes very hard for a human to check. - Author in the **base currency** and ignore tax. Currency conversion, customer-group overrides and tax are applied on top of the result. - The calculation edit form lists **where it is in use** — check that before editing a shared table. ## Troubleshooting - **The price doesn't move.** The calculation is probably not attached yet (step 6), or the axis question is on a page the customer hasn't reached. - **Every configuration gets the same price.** One axis is likely set to **Ignored**, or the question you picked isn't the one the customer is answering. - **The price jumps at the wrong point.** Check **Lookup Value** — *next higher* and *next lower* shift every bracket boundary by one step. - **Round Values to seems to do nothing.** It only applies with **Exact Value**; with either *next* mode it is ignored by design. - **The import filled the wrong cells.** On an axis whose question has predefined answers the file's first row/column is ignored — strip that header from the sheet, or expect it to be dropped. --- # Charge recurring (subscription) prices Page: https://docs.configbox.at/docs/admin-guide/pricing/recurring-pricing > **Audience:** store admins · **Scope:** recurring (subscription) pricing on a product · **Last reviewed:** 2026-07-23 **What this does** — Recurring pricing lets a product carry a **repeating** charge — a monthly plan, a service subscription — *alongside* its one-off price. The customer sees both a one-time total and a recurring total, and the two are tracked separately through cart and checkout. ## Before you start - Decide what recurs: the whole product (a subscription product with a recurring **base price**), or specific **answers** (an add-on billed monthly). This article uses the second, more common case. - Author amounts in the **base currency**, tax-exclusive — currency, group overrides and tax apply on top, exactly as for one-off prices ([where prices come from](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from)). ## Steps 1. **Turn recurring pricing on for the product.** Open the product's edit form and set **Does the product also use recurring pricing?** to **Yes**. The product then carries its own recurring **base price** and a recurring **tax class** in parallel with the one-off ones, and a recurring price label (the interval, e.g. "monthly"). Leave the recurring base price at 0 if only add-ons recur. 2. **Set the recurring amount on the answer.** Open the answer, expand its **Price, SKU and Weight** section, and enter the amount in **Price Recurring** — the euro field just below **Price** and **Was Price**: ![The answer's Price Recurring field](img/recurring-answer.jpeg) A **Was Price Recurring** shows a struck-through before-price for the recurring amount, just like Was Price does for the one-off one. 3. **Save.** Here the "Add a laundry-care plan" question's answer "Monthly laundry-care plan" has **Price** 0 and **Price Recurring** 9.90. ## What happens next On the storefront the answer shows its recurring amount labelled distinctly — "€ 9.90 Recurring Price" — and the live price summary lists the recurring line **separately** from the one-off total, so the customer sees "pay this once, then this every cycle". ## Good to know - How much of the recurring breakdown the summary shows — overall, per question, taxes — is set in the **Selection overview** section of **Settings**, with its own switches for recurring pricing (see [tour the Settings sections](https://docs.configbox.at/docs/admin-guide/settings/tour-the-settings-sections)). - Nearly every price field has a recurring twin: base price, answer price, per-group/per-currency overrides. Fill only the ones that recur. - Weight-based shipping and one-off surcharges are unaffected — recurring pricing runs alongside the normal price, it doesn't replace it. --- # Set product weight for shipping Page: https://docs.configbox.at/docs/admin-guide/pricing/weight-and-shipping-weight > **Audience:** store admins · **Scope:** the weight that drives weight-based shipping · **Last reviewed:** 2026-07-23 **What this does** — Weight is what weight-based shipping prices delivery from. Each **answer** can add weight, and the product carries a base weight; CBX sums them for the configured product and hands the total to the shipping calculation. ## Before you start - **Shipping must be on.** If **Disable Shipping** is ticked in **Settings**, weight is irrelevant and its fields don't matter — see [tour the Settings sections](https://docs.configbox.at/docs/admin-guide/settings/tour-the-settings-sections). - Know your store's **weight unit** (set in **Settings**, Configurator section — here **kg**) and enter every weight in it consistently. ## Steps 1. Open an answer, expand its **Price, SKU and Weight** section, and enter the **Weight** field — the amount this choice adds to the configured product's total, in the store's weight unit: ![The answer's Weight field](img/weight-answer.jpeg) Here the "Linen" fabric answer weighs **0.2 kg** (Cotton 0.18, Silk 0.15). 2. **Save**, and repeat for the answers whose choice changes the shipping weight. 3. Give the **product** its base/shipping weight on the product form — the fixed weight the item always has before any answer adds to it. ## What happens next At checkout, CBX adds the product's base weight and every selected answer's weight, then the shipping method prices delivery from that total (by weight band and zone). The customer sees the resulting shipping cost in the cart and the live summary if you enabled it. ## Good to know - **Weight works just like price**: static per answer, or **computed by a calculation** when the weight depends on the configuration (e.g. area × density). Attach a weight calculation the same way you attach a price one — see [build a calculation](https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation). - Keep the unit consistent — the store has one weight unit; mixing grams and kilograms silently wrecks shipping bands. - Weight is separate from price: an answer can add weight without adding cost, and vice versa. - No shipping method reacting to weight? Check the method's weight bands in the commerce system, and that shipping isn't disabled in **Settings**. --- # Where prices come from Page: https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from > **Audience:** store admins · **Scope:** the pricing model, before you build anything · **Last reviewed:** 2026-07-20 **What this does** — Explains every place a price can be set and how they combine into the total the customer watches while configuring. Knowing this map, you'll put each price in the right place on the first try. How the pieces assemble, whenever the customer changes anything: ```mermaid flowchart LR BP["Product base price"] --> SUM["Configured price\n(recomputed live)"] AP["Static prices per answer"] --> SUM CALC["Calculations\n(formula / matrix / code)"] --> SUM SUM --> ADJ["Customer-group overrides\n· currency · taxes"] ADJ --> SHOW["What the customer sees"] ``` ## The building blocks, in the order they add up 1. **Product base price** (product form) — the starting amount before any selections, with its **tax class**. 2. **Answer prices** (answer form) — each selected answer adds its static **Price**. This is the workhorse: for most products, base price + answer prices is the whole story. 3. **Question price calculations** (question form → Calculations) — a question whose price must be *computed* (e.g. a text/slider question priced by the entered dimensions) gets a **Price Calculation** instead of static prices; an optional **Price Multiplicator** scales the result (e.g. by a quantity). 4. **Answer price calculations** (answer form → Calculations) — a calculation attached to an answer **overrides** its static price for that question. Use it when one choice's surcharge depends on other selections. 5. **Delivery and payment** — shipping cost (by weight and zone) and any payment-method surcharge are added at checkout; they can be previewed in the live summary if enabled. On top of the summed raw prices, CBX automatically applies: - **Currency conversion** — you author every amount in the **base currency**; other currencies convert by their multiplier. - **Per-currency / per-group price overrides** — explicit amounts you pin for a specific currency or customer group (on products and answers) beat the converted value. - **Customer-group discounts** — volume-discount tiers from the customer's group, applied in the cart. - **Tax** — per the item's tax class and the customer's place and B2B/B2C mode. Never put tax into a price or formula. Regular and **recurring** (subscription) pricing run in parallel: nearly every field above has a "… Recurring" twin, and the storefront shows both totals for products that use both. ## Choosing the right mechanism | You want | Do this | |---|---| | "Leather seats cost €200 extra" | static **Price** on the answer | | "Price is width × height × rate" | **Formula calculation** on the question | | "This coating's surcharge depends on the chosen size" | calculation on the **answer** | | "Glass price per size/thickness bracket" | **Matrix calculation** | | "10% handling on everything" | **Code calculation** using the running total | | "Trade customers pay less for everything" | customer-group **discounts** or per-group **overrides** — not formulas | | "Max quantity depends on the chosen package" | a calculation as the question's **calculated maximum** | ## Seeing what the customer sees The live **selection overview** beside the configurator itemizes prices per question and page — its detail level is configurable globally (**Settings**) and per product. When checking your pricing, configure the product on the storefront and watch the overview react to each change; every number should be explainable by one of the building blocks above. ## Good to know - A calculation does nothing until it's **attached** to something — a question's or answer's price/weight, a min/max bound, a rule condition, or another calculation. - **Weight** works like price: static per answer, or computed by a weight calculation — the cart weight then drives weight-based shipping. - **Was prices**, **price labels** ("from") and **custom price text** ("call for quote") change how a price is *presented*, not what is charged. - Whether a customer group sees prices at all (or can only request a quote) is a **customer group** permission — see the commerce system. --- # Write a code expression Page: https://docs.configbox.at/docs/admin-guide/pricing/write-a-code-expression > **Audience:** store admins · **Scope:** the Code calculation style · **Last reviewed:** 2026-07-21 **What this does** — Lets you *type* a pricing formula instead of assembling it from drag-and-drop chips. It is the same engine as the Formula style with a different way in: quicker for short arithmetic, and the only style that can read the running **total** of the configuration. Despite the name, this is not programming. An expression is a line of school arithmetic — numbers, `+ - * /`, brackets — where some of the numbers are written as keywords that CBX replaces with live values from the customer's configuration. ## Before you start - Read [where prices come from](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from) and [build a calculation](https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation) — a code expression is one of the three calculation styles, and is created, saved and attached exactly like the others. - Have the **IDs** of the questions and calculations you want to read. Question IDs appear next to the title in the placeholder drop-downs (`Motor Power (ID: 2)`) and in the questions list; calculation IDs are in the **Calculations** list. - If the formula only reads questions the customer types into, you may not need any keyword at all — the A–D placeholders will do. ## Steps 1. Go to **Calculations**, click **Add**, name the calculation, choose the **product** and pick the style **Code**. 2. Bind up to four questions to the placeholders **A**, **B**, **C** and **D** using **Question for placeholder A** … **D**. Leave the rest on **Not used**. ![The code editor: a threshold expression on placeholder A, chaining another calculation](img/calculation-code.jpeg) 3. Type the expression in the **Code** box. The screenshot's formula is an area price in square metres: two questions in millimetres bound to A and B, then ``` A * B / 1000000 * 65 ``` 4. **Save**, then **attach it** — nothing is calculated until the calculation is set as a question's or answer's **Price Calculation** (or Recurring Price / Weight Calculation), used as a calculated minimum/maximum, or referenced from a rule or another calculation. See [build a calculation](https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation). 5. Open the configurator and check the number against a calculator. Always check a code expression live — it is accepted as typed, without a preview. ## The three rules that break formulas The editor's own **Notes** section states them, and almost every broken expression breaks one: 1. **A dot is the decimal mark.** `0.25`, never `0,25`. 2. **No thousands separators.** `1000000`, never `1 000 000` or `1,000,000`. 3. **A space before and after every placeholder and keyword.** `A * B`, not `A*B`. The values are substituted textually, so a missing space glues two numbers together. Placeholders accept numbers only. Bind them to text-field questions with numbers-only validation, and an empty field counts as `0`. ## Keyword reference Every keyword is replaced with a live value from the configuration the customer is building. | Keyword | Value it produces | |---|---| | `Total` | The running total of the configuration. **Once per product only** | | `TotalRecurring` | The running recurring total. **Once per product only** | | `QuestionPrice(id)` | The current price of that question | | `QuestionPriceRecurring(id)` | The current recurring price of that question | | `QuestionSelection(id)` | What the customer typed into that question — numbers only; empty counts as `0` | | `QuestionProperty(id.path)` | Any attribute of that question or its selected answer (see below) | | `Calculation(id)` | The result of another calculation of this product | `QuestionSelection(id)` does exactly what an A–D placeholder does. Use the placeholders while you have four or fewer questions — they read better — and fall back to the keyword beyond that. ### QuestionProperty paths Write the question ID, a dot, then the attribute. Using question 22 as the example: | Path | What it reads | |---|---| | `QuestionProperty(22.selectedAnswer.weight)` | The weight of the answer the customer picked | | `QuestionProperty(22.question_custom_1)` … `_4` | The question's own custom fields (question screen → **Custom Fields**) | | `QuestionProperty(22.selectedAnswer.assignment_custom_1)` … `_4` | The selected answer's custom fields, from the answer screen | | `QuestionProperty(22.selectedAnswer.option_custom_1)` … `_4` | The selected answer's *global* custom fields, from the answer screen | Custom fields are how you attach your own numbers — a material factor, a supplier code, a labour rate — to a question or an answer and price from them, without inventing a hidden question. ### Reading the question you are attached to `RegardingQuestion` means "whichever question or answer this calculation is attached to". A calculation written with it can be attached to many questions at once and always reads its own: | Keyword | What it reads | |---|---| | `RegardingQuestion(question_custom_1)` | Custom field 1 of the question using this calculation | | `RegardingQuestion(regardingAnswer.weight)` | The weight of the answer using this calculation | | `RegardingQuestion(regardingAnswer.assignment_custom_1)` | Custom field 1 of the answer using this calculation | This is what turns ten near-identical formulas into one. ## Worked examples **Area price.** Width and Height are text fields in millimetres, bound to A and B; the rate is €65 per square metre: ``` A * B / 1000000 * 65 ``` **A percentage of the whole configuration.** Attach to the question that should carry the surcharge — an insurance or service option, for instance: ``` Total * .25 ``` The demo store's *Phone with Contract* product does exactly this, and the recurring twin `TotalRecurring * .25` for the monthly side. Remember the once-per-product limit: only one calculation in a product may read `Total`. **Price from a custom field.** The material factor sits in custom field 1 of each answer of question 30, and the base rate comes from a text field bound to A: ``` A * QuestionProperty(30.selectedAnswer.assignment_custom_1) ``` **Composing calculations.** Keep pieces small and readable, then combine them: ``` Calculation(14) + Calculation(15) ``` **Reusable per-question rate.** One calculation attached to every answer that carries a rate in its custom field 1, multiplied by the entry in A: ``` A * RegardingQuestion(regardingAnswer.assignment_custom_1) ``` ## Good to know - **Code and Formula are equally powerful for arithmetic** — pick whichever *you* will still understand in six months. The one thing only Code can do is read `Total` / `TotalRecurring`. - **Compose, don't inflate.** Several small named calculations referencing each other with `Calculation(id)` stay debuggable; one long line does not. - **Watch the ID.** Keywords address questions by number, so a formula that reads `QuestionProperty(30…)` breaks silently if question 30 is deleted. The calculation edit form lists where a calculation is in use; there is no equivalent warning in the other direction. - **Author in the base currency and ignore tax.** Currency conversion, customer-group overrides and tax are applied on top of the result. - Copying a product copies its code calculations and re-points every reference. ## Troubleshooting - **The price is 0 or blank.** A placeholder is bound to a question the customer hasn't reached, or to one that isn't numbers-only. Empty entries count as `0`, and anything multiplied by `0` is `0`. - **The result is wildly wrong.** Look for a missing space around a placeholder, a comma used as a decimal mark, or a thousands separator. - **`Total` gives a strange number.** Check that no second calculation in the same product also uses `Total` — it may be used only once per product. Also remember it is the total *so far*, so a percentage-of-total surcharge should sit on a late page. - **Nothing calculates at all.** The calculation isn't attached yet. Creating it is only half the job — see step 4. --- # Products & configurator Page: https://docs.configbox.at/docs/admin-guide/products/ > **Audience:** store admins · **Scope:** building what your customers configure and buy · **Last reviewed:** 2026-07-25 **TL;DR** — A configurable product is a small hierarchy: the **Product** carries pricing and presentation, its **Pages** are the configuration steps, each page holds **Questions** (the inputs), and choice questions offer **Answers**. You build all of it from the product tree under **Products** — and everything you build shows up live on the storefront. > **Platform note (Magento 2):** this system **fully applies** on Magento-hosted stores — with one > exception: **product lists** are Magento's job (its catalog does that), and the Product Lists > screen is hidden there. See [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/). ## Articles 1. **[How a product fits together](https://docs.configbox.at/docs/admin-guide/products/how-a-product-fits-together)** — the mental model to read before building anything. 2. **[Add a product](https://docs.configbox.at/docs/admin-guide/products/add-a-product)** — create the product record: titles, listings, images, base price, visibility. 3. **[Add pages and questions](https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions)** — the configuration steps and the inputs on them, including all question types. 4. **[Add answers to a question](https://docs.configbox.at/docs/admin-guide/products/add-answers)** — the choices customers pick from: prices, images, defaults, ordering, availability. 5. **[Set up the visual preview](https://docs.configbox.at/docs/admin-guide/products/set-up-the-visual-preview)** — 2D composite layers or a 3D ShapeDiver model that update with every choice. 6. **[Manage product lists](https://docs.configbox.at/docs/admin-guide/products/manage-product-lists)** — the catalogs your storefront shows. 7. **[Add product detail panes](https://docs.configbox.at/docs/admin-guide/products/product-detail-panes)** — the titled info blocks (specs, care, delivery) on a product's storefront detail page. 8. **[Copy and retire products](https://docs.configbox.at/docs/admin-guide/products/copy-and-retire-products)** — duplicate a product's structure, and take a product offline without deleting its history. 9. **[Edit from the storefront as a manager](https://docs.configbox.at/docs/admin-guide/products/edit-from-the-storefront)** — tweak questions and answers inline, while looking at the live configurator. 10. **[Move products between sites](https://docs.configbox.at/docs/admin-guide/products/move-products-between-sites)** — export a product and everything belonging to it as a package, and import it into another CBX install: staging to live, or one client's site to another. ## Where everything lives Open **Products** in the CBX menu — the product tree is your home base: ![The product tree](./img/product-tree.jpeg) Every product expands to its pages, questions and answers; clicking any node opens its edit form, and **Add product** at the bottom starts a new one. The other entry point is the storefront itself: as a logged-in manager you get edit buttons on hover, opening the same forms in context. --- # Add a product Page: https://docs.configbox.at/docs/admin-guide/products/add-a-product > **Audience:** store admins · **Scope:** the product form · **Last reviewed:** 2026-07-20 **What this does** — Creates the root record of a configurable product: what it's called, where it appears, what it looks like, and what it costs before any options are added. Pages, questions and answers come afterwards. ## Before you start - Know the product's name in every active shop language, its starting price, and which product list(s) it should appear in. - Have a product image ready (used on lists and the detail page). ## Steps 1. Go to **Products** and click **Add product** at the bottom of the tree (or tick an existing product and use **Copy** for a head start). 2. Fill the **General** section: ![The product form, General and Visualization sections](./img/product-edit.jpeg) - **Title** — per language; shown everywhere the product appears. - **SEF Segment** — per language; the product's URL slug (e.g. `shirt-configurator`). - **In which product lists do you want to show this product?** — tick the catalogs that should carry it. A product in no list is only reachable by direct link. - **Product Image** — upload the main image. File fields show the current file with **Replace file** and a **Delete file at save** tick. - **Should the product be displayed?** — the master visibility switch. Keep it on **No** while building; flip to **Yes** to go live. 3. In **Visualization**, pick what customers see while configuring: **No visualization**, **Composite Image** (2D layered preview — set the **Base image** here, per-answer overlays come later on the answers), or **ShapeDiver** (3D). 4. In **Base price**, set the starting price before any options, and the product's **tax class**. A parallel **Base price Recurring** section exists for subscription-style pricing — leave it empty unless you sell recurring. 5. Skim the display sections — each has sensible defaults you can tune later: - **Display in product detail page** — detail-page type, long description, detail panes on/off. - **Display in product listings** — the buy/details buttons on list tiles, reviews on/off, short listing description. - **Display in configurator** — per-product overrides for tab/button navigation, whether continuing is blocked while required answers are missing, and the cart button placement. Each can defer to the global default from **Settings**. 6. **Save**. ## What happens next The product appears in the tree — now [add its pages and questions](https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions). Once **displayed** is on Yes, it is live in every list you ticked. ## Good to know - **Price display extras:** **Was Price** shows a struck-through before-price; **Price Label** (e.g. "from") and **Custom Price Text** (e.g. "Call for quote") adjust how the price reads. - **Custom fields** (in their own section) are free-form product attributes whose labels you define once in **Settings** — useful with rules, calculations and templates; ignore them until you need them. - **Copying a product** copies everything — pages, questions, answers, rules, calculations — and re-points all internal references to the copy. It is the recommended way to build variants. --- # Add answers to a question Page: https://docs.configbox.at/docs/admin-guide/products/add-answers > **Audience:** store admins · **Scope:** the Predefined Answers of a choice question · **Last reviewed:** 2026-07-20 **What this does** — Fills a choice-type question (radio buttons, dropdown, checkbox, clickable images) with its selectable **answers** — each with its own price, image, description, availability and position. ## Before you start - Create the [question](https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions) with a choice type. - Know each answer's price effect (a fixed surcharge? computed? free?) and have images ready if the question shows pictures. ## Steps 1. Open the question. In **Predefined Answers** you see the answer table — ID, ordering handle, SKU, price, title, rule, calculation, default, active: ![A question's Predefined Answers](./img/question-edit.jpeg) 2. Click **Add** to create an answer (or tick + **Copy** an existing one), and fill its form: - **Title** — per language; what the customer reads. - **Price** — the amount this answer adds to the product. **Price Overrides** can pin explicit amounts per currency or customer group; a **Was Price** shows a struck-through before-price. Parallel **recurring** fields exist for subscription pricing. - **SKU** — the answer's article number; can be shown on order line items. - **Weight** — what this answer adds to the cart weight (relevant for weight-based shipping). - **Default** — preselect this answer when the customer arrives. - **Picker Image** — the image used in clickable-image questions; a **Visualization Image** (plus stacking order) is the overlay layer for the product's 2D composite preview. - **Availability**: **Available** switches the answer on/off; **Availability date** makes it selectable only from a date, and "disable when not available" shows it greyed-out with an "Available on …" note instead of hiding it. 3. **Save**, and drag the rows into the order customers should see. The **Active** check in each row publishes/unpublishes the answer in place. ## What happens next Answers show up in the configurator immediately, with their price effects in the live summary. The row's **Rule** and **Calculation** columns show at a glance which answers carry conditional visibility or computed pricing. ## Good to know - **An answer belongs to exactly one question.** To offer the same choice on another question, copy the answer there — the copies are independent afterwards (its price, rule and images can differ per question, which is usually exactly what you want). - A **calculation** attached to an answer overrides its static price — see [where prices come from](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from). - A **rule** on an answer shows/hides that single choice — see [build a rule](https://docs.configbox.at/docs/admin-guide/rules/build-a-rule). "Display while disabled" chooses between hiding and greying out. - **Answer custom fields** (labels defined in **Settings**) attach free-form data to an answer that rules and calculations can read — e.g. a "mounting-holes" number a formula uses. - Deleting an answer that rules or calculations reference is blocked with a message naming the dependency; deactivate instead if you just want it off the storefront. --- # Add pages and questions Page: https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions > **Audience:** store admins · **Scope:** pages and the question form · **Last reviewed:** 2026-07-20 **What this does** — Gives your product its configuration steps (**pages**) and the inputs on them (**questions**). After this, choice questions still need [answers](https://docs.configbox.at/docs/admin-guide/products/add-answers). ## Before you start - Sketch the flow on paper first: which steps, in which order, which inputs on each. Restructuring later works, but a five-minute sketch saves an hour of dragging. - [Create the product](https://docs.configbox.at/docs/admin-guide/products/add-a-product) first. ## Add a page 1. In **Products**, expand your product and add a page (or open an existing one). 2. Give it a **Title** per language (the step's tab label), an optional **Description** (intro text on the step), and keep **Active** on. **Ordering** controls the step sequence. 3. **Save**. ## Add a question 1. Expand the page in the tree and add a question. The question form opens: ![The question form](./img/question-edit.jpeg) 2. In **General**: - **Title** — per language; the question text customers see. - **Does the question have to be answered?** — Yes makes it required; combined with the product/global setting, customers can be blocked from continuing while it's unanswered. - **How do you want to display the question?** — the question type (see the table below). This choice decides which further sections the form shows. 3. Fill the type-specific settings (only the relevant ones appear — see the table). 4. **Save**. For choice-type questions, the **Predefined Answers** section is where you [add the answers](https://docs.configbox.at/docs/admin-guide/products/add-answers). ## The question types | Type | Customer sees | Typical use | |---|---|---| | Radio buttons | one-of-N choices, all visible | short choice lists | | Dropdown | one-of-N in a select box | long choice lists | | Checkbox | a single on/off tick | include/exclude a feature | | Clickable images | picture grid, single or multi select | visual choices (colors, designs) | | Text box | a one-line input, optional unit suffix | names, dimensions, quantities | | Multi-line text box | a larger text area | notes, engraving text | | Slider | a draggable slider synced to a number field | dimensions within a range | | Calendar | a date picker | delivery/booking dates | | Color picker | a free color choice | custom colors | | RAL color picker | the standardized RAL swatch catalog | industrial colors | | File upload | drag-and-drop upload | customer artwork, documents | | Choices + text field | predefined values plus a custom entry | "pick one or type your own" | Type-specific settings worth knowing: - **Text-style types** (text box, slider, …): prefill a **default value**; restrict input (e.g. integers only); set **minimum/maximum** either as static values or **calculated** by a calculation (so a limit can depend on other selections); show a **unit** next to the field. - **Slider**: the number of steps. - **Calendar**: first day of week and how far into the past/future dates may lie. - **File upload**: allowed extensions, allowed file kinds, maximum size. ## What happens next Pages and questions appear in the configurator immediately (for a displayed product). Questions on a page render in their **Ordering**; required ones gate navigation if blocking is enabled. ## Good to know - **Internal Name** — an admin-only label for the question, invaluable once a product has dozens of questions. Enable "show internal names" in **Settings** to see them across the back office. - The **Rule** section on this form is where conditional visibility attaches — [build a rule](https://docs.configbox.at/docs/admin-guide/rules/build-a-rule). - The **Calculations** section is where computed pricing attaches — [where prices come from](https://docs.configbox.at/docs/admin-guide/pricing/where-prices-come-from). - **Show in Overview** controls whether the question appears in the live price/selection summary beside the configurator. - A question's **Image** and **Description** (with a display method: inline, tooltip …) add help content customers see with the question. --- # Copy and retire products Page: https://docs.configbox.at/docs/admin-guide/products/copy-and-retire-products > **Audience:** store admins · **Scope:** duplicating and taking down products · **Last reviewed:** 2026-07-23 **What this does** — Two housekeeping jobs. **Copy** duplicates a whole product — its pages, questions and answers — so you can build a variant without starting over. **Retire** takes a product off the storefront without deleting it, so its past orders stay intact. ## Before you start - Both actions live on the flat **Products** list — open **Products** in the CBX menu. (This is the list view; the product **tree** is the other way in.) ![The Products list with Add, Remove and Copy](img/products-list-copy.jpeg) The list shows each product's ID, **Title**, **Product SKU**, **Base Price**, **Base Price Recurring**, **Should the product be displayed?** and its product list. ## Copy a product 1. Tick the checkbox next to the product you want to duplicate. 2. Click **Copy**. CBX creates a new product carrying the whole structure — every page, question and answer, with their prices and rules. 3. Open the copy and rename it (and its SEF segment), adjust what differs, and place it in the right [product lists](https://docs.configbox.at/docs/admin-guide/products/manage-product-lists). The copy is fully independent of the original. ## Retire a product (take it offline) 1. Open the product's edit form (**Product: …**). 2. In **General**, set **Should the product be displayed?** to **No**. 3. **Save**. The product vanishes from the storefront and its list pages immediately, but the record — and every order ever placed for it — stays exactly as it was. Set it back to **Yes** to bring it back. ## What happens next A copied product is live the moment you place it in a displayed list and set it to display. A retired product disappears from browsing and direct links, while its order history stays readable in **Orders**. ## Good to know - **Retire, don't Remove, for products that have sold.** **Remove** (the button beside Copy) deletes the product permanently; a product referenced by past orders should be retired instead, so the order records stay complete. - Copy is the fast way to make a "same but different" product — a second size range, a seasonal variant — then prune what you don't need on the copy. - Retiring the product doesn't touch its [detail panes](https://docs.configbox.at/docs/admin-guide/products/product-detail-panes) or calculations; they come back with it when you display it again. --- # Edit from the storefront as a manager Page: https://docs.configbox.at/docs/admin-guide/products/edit-from-the-storefront > **Audience:** store admins · **Scope:** in-context editing from the storefront · **Last reviewed:** 2026-07-23 **What this does** — When you're signed into your site as a store manager, the storefront configurator gains **inline edit controls**. You can adjust a question or answer while looking at the live product — the exact thing the customer sees — instead of guessing from the back-office form. ## Before you start - Be **logged into your site** with a manager/administrator account (the same account you use for the CBX back office). - Open the product on the storefront and start configuring it: ![The Shirt Configurator on the storefront](img/storefront-editing.jpeg) ## Steps 1. Hover a question or answer. As a logged-in manager you get an inline edit control on it that a normal shopper never sees. 2. Click it. The matching back-office edit form opens **in context** — the same question or answer form you'd reach from **Products**, but launched from where you were looking. 3. Change the label, price, ordering or rule, and **Save**. 4. Reload the storefront page to see the change live, and keep going. ## What happens next Your edit is a normal back-office change — it takes effect for every customer immediately. The inline controls are only ever shown to signed-in managers; shoppers see the clean configurator. ## Good to know - This is the "build a little, then look at the storefront" loop from [how a product fits together](https://docs.configbox.at/docs/admin-guide/products/how-a-product-fits-together) — it just saves the round trip back to the admin tree for small tweaks. - The forms you reach this way are the same ones documented in [add pages and questions](https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions) and [add answers](https://docs.configbox.at/docs/admin-guide/products/add-answers); the fields and rules behave identically. - For structural work — adding pages, reordering the tree, bulk changes — the back-office **Products** screens are still the better place; inline editing shines for quick, in-place fixes. --- # How a product fits together Page: https://docs.configbox.at/docs/admin-guide/products/how-a-product-fits-together > **Audience:** store admins · **Scope:** the concepts behind every configurable product · **Last reviewed:** 2026-07-20 **What this does** — Five minutes of orientation that make every other article in this system obvious. Read it once; skim it again whenever a form field puzzles you. ## The hierarchy ``` Product "Shirt Configurator" └─ Page step 1: "Fabric & Fit" └─ Question "Which fabric?" (radio buttons, required) └─ Answer "Linen" (+ €20, picture, selected by default) ``` - **Product** — the thing being sold. Carries the base price, tax class, images, which catalogs it appears in, and how its detail page and configurator behave. - **Page** — one step of the configurator. Customers move through pages with tabs and/or next-previous buttons; each page has a title and optional intro text. - **Question** — one input on a page. Its **question type** decides the widget: radio buttons, dropdown, checkbox, clickable images, text box, multi-line text, slider, calendar, color picker, RAL color picker, file upload, or predefined choices with a free-text extra. - **Answer** — one selectable choice of a question (for the choice-type questions). An answer belongs to exactly one question and carries its own price, image, description, availability and ordering. ## What attaches to the hierarchy - **Rules** — on questions and answers. A rule decides whether that question/answer is shown, based on other selections or on who the customer is. This is what makes the configurator reshape itself as customers choose. → [Rules](https://docs.configbox.at/docs/admin-guide/rules/) - **Calculations** — named formulas belonging to the product. Attach one to a question or answer and its price (or weight, or an input's min/max bound) becomes computed instead of static. → [Pricing & calculations](https://docs.configbox.at/docs/admin-guide/pricing/) - **Visual preview** — per product you choose none, **Composite Image** (2D: a base image plus one overlay layer per selected answer) or **ShapeDiver** (interactive 3D; questions and answers drive model parameters). → [Set up the visual preview](https://docs.configbox.at/docs/admin-guide/products/set-up-the-visual-preview) - **Detail panes** — the tabbed info blocks on the product's detail page (specs, delivery info…). - **Product Lists** — the catalogs on your storefront; a product appears in the lists you tick on its form. → [Manage product lists](https://docs.configbox.at/docs/admin-guide/products/manage-product-lists) ## What the customer experiences The storefront side of everything above: a product list → a product detail page → the configurator, stepping through your pages with a live price summary, a live preview, questions appearing and disappearing per your rules — then add-to-cart and checkout. ![A product list on the storefront](./img/storefront-listing.jpeg) ## The build workflow (and the reading order) 1. **[Create the product](https://docs.configbox.at/docs/admin-guide/products/add-a-product)** — title, list placement, base price, visibility. 2. **[Add pages, then questions](https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions)** — the steps and their inputs. 3. **[Add answers](https://docs.configbox.at/docs/admin-guide/products/add-answers)** — the choices, with prices and images. 4. **Add logic** — [rules](https://docs.configbox.at/docs/admin-guide/rules/) for show/hide behavior. 5. **Price it properly** — [calculations](https://docs.configbox.at/docs/admin-guide/pricing/) where static prices aren't enough. 6. **Merchandise** — the [visual preview](https://docs.configbox.at/docs/admin-guide/products/set-up-the-visual-preview), detail panes, [list placement](https://docs.configbox.at/docs/admin-guide/products/manage-product-lists), reviews. Build a little, then look at the storefront, then build more — the configurator is live the moment the product is displayed, and managers can even edit right from the storefront. --- # Manage product lists Page: https://docs.configbox.at/docs/admin-guide/products/manage-product-lists > **Audience:** store admins · **Scope:** the Product Lists screen · **Last reviewed:** 2026-07-20 **What this does** — Product lists are the catalogs customers browse ("Demo Products" in the demo store). A list decides which products appear together and in what order; a product can sit in several lists, and a list typically backs one storefront page. > **Platform note:** on **Magento 2** product lists don't exist — Magento's own catalog plays > that role, so the menu entry is absent by design. On **Joomla** and **WordPress** a list > becomes a storefront page only when something points at it: on Joomla create a **menu item** > of type *CBX → Product List*; on WordPress the plugin maintains a page per list > automatically, and you can also place one on any page with the > `[configbox view="productlist" id="…"]` shortcode. See > [CBX on Joomla](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-joomla) and > [CBX on WordPress](https://docs.configbox.at/docs/admin-guide/getting-started/platform/cbx-on-wordpress). ## Steps 1. Go to **Product Lists**, open a list or **Add**: ![The product list form](./img/product-list-edit.jpeg) 2. The fields: - **Title** per language, and an optional **Description** shown atop the list page. - **Template** — the layout that renders this list (Default unless your site has custom layouts). - **Active** — live or not. - **Sort products by** — **Title** (alphabetical) or manual: with manual sorting, drag the rows in **Products in this list** into the order you want on the storefront. 3. Manage membership from either side, whichever is handier: - here: **Add** / **Remove** products in the **Products in this list** table, or - on the product form: tick the lists under *"In which product lists do you want to show this product?"*. 4. **Save**. ## What happens next The storefront list page reflects membership and order immediately. Each tile shows the product's image, title, price block and (if enabled) review stars — what the tile offers (buy/details buttons, short description) is set per product in its *Display in productlistings* section. ## Good to know - A product in **no** list is reachable only by direct link — fine for hidden or link-only offers, usually an oversight otherwise. - **Settings → Checkout → Product List for continue shopping** picks the list customers return to after adding to cart — point it at your main catalog. - Lists are also a scoping device in the back office: the product tree's filter dropdown narrows to one list. --- # Move products between sites Page: https://docs.configbox.at/docs/admin-guide/products/move-products-between-sites > **Audience:** store admins · **Scope:** exporting and importing products between installations · **Last reviewed:** 2026-08-04 **What this does** — Builds a product a second time somewhere else, without rebuilding it. You export one or more products to a single file, then import that file on another CBX site. The file carries the whole product: its configurator pages, questions, answers, prices, calculations, rules and images. The usual reason is a **staging site**: you build and test a product where customers cannot see it, then move the finished thing to the live store. ## Before you start - Open **Product Transfer** in the CBX menu. - You need the same access on both sites — the one you export from and the one you import into. - Importing changes the receiving site. On a live store, take a database backup first. ## Export products 1. Use the filters to find what you want — search by **title or SKU**, narrow by **status** (published or unpublished), or pick a **product list**. 2. Tick the products to include. The counter next to the button shows how many are selected. 3. Click **Export selected**. Your browser downloads one `.zip` file containing every product you ticked. The file is a transfer file, not a backup — it holds the products you picked and nothing else. ## Import a package 1. On the receiving site, open **Product Transfer** and choose the file under **Package file**. 2. Choose how the products should be created: - **Create as new products** — the products are added alongside what is already on the site, each getting a new ID. Use this when you are bringing a product *in*. - **Keep the original IDs (overwrite)** — the products replace the ones they came from, and anything the receiving site has that the file does not is removed. Use this to push an updated product from staging to live, so the two end up identical. 3. Click **Check package**. Nothing is written yet — CBX reads the file and reports what importing it would do. ## Read the check before you confirm The check lists what it found, in three strengths: | Strength | What it means | |---|---| | **Blocker** | The import cannot run. Fix what it names, then check the file again. | | **Warning** | The import can run, but something will be lost or is not quite right. You decide. | | **Notice** | Just so you know — no decision needed. | Every warning has a tick box, and **Import now** stays disabled until you have ticked them all. The common ones: - **The CBX versions differ.** The two sites are on different versions of ConfigBox. This is often fine — it is telling you so you are not surprised. - **A referenced record does not exist here.** The product points at something the receiving site does not have, such as a tax class or a customer group. CBX never creates these for you, because it cannot know your rates or prices are the same. Create the missing record first if it matters, or accept that the field will be left empty. - **Products will be overwritten.** Only in *Keep the original IDs* mode. - **Saved cart data will be deleted.** Also only in that mode: removing a question that customers have answered removes their saved answers with it. The message tells you how many. **This cannot be undone.** ## While it imports Click **Import now** and CBX works through the file one product at a time, showing a progress bar and listing each product as it lands. Large packages are handled in small steps on purpose, so nothing times out. If the page is interrupted — a dropped connection, a closed laptop — the products already imported stay imported. Each product is written completely or not at all, never half. ## After importing - Open each imported product and check it over: its pages, its prices, and anything the check warned you about. - In **Create as new products** mode the imports arrive with the same titles as the originals. Rename them and their SEF segments if both are to live on the same site. - Publish them when you are happy — an import does not change what is on the storefront until the product is published. ## Without a browser, for a scripted deploy If the transfer is a step in a deployment rather than something you do by hand, both halves have a command-line equivalent. They do exactly what the screen does, against the install whose checkout they are run from: ```bash php tools/export-product-package.php --sku=YOUR-SKU -o /tmp/product.zip # on the source php tools/import-product-package.php /tmp/product.zip --mode=exact --force # on the target ``` The importer runs the **same check** the screen does and refuses on a blocker. `--force` is how you accept the warnings: nobody is at the keyboard to read them, so they have to be accepted deliberately rather than by default. `--dry-run` reports what would happen and imports nothing. Ask your developer or host to run these — they need shell access to the site's files. --- # Add product detail panes Page: https://docs.configbox.at/docs/admin-guide/products/product-detail-panes > **Audience:** store admins · **Scope:** the Product Detail Panes of one product · **Last reviewed:** 2026-07-23 **What this does** — Detail panes are the titled information blocks shown on a product's storefront **detail page** — specifications, care instructions, delivery terms, anything a buyer wants to read before configuring. Each pane is a heading plus rich-text content; a product can have several. ## Before you start - Have the [product](https://docs.configbox.at/docs/admin-guide/products/add-a-product) created. - Write the copy for each pane, in every active language. ## Steps 1. Open **Products → Product Detail Panes** in the CBX menu. The list has **Add**, **Remove** and **Copy**, a product filter and a **Filter by Heading** box, and shows each pane's ID, ordering handle and **Heading**: ![The Product Detail Panes list](img/detail-panes-list.jpeg) 2. Pick the product from the filter dropdown (so a new pane attaches to it), then click **Add** — or open an existing pane's heading to edit it. 3. Fill the **Product Detail Pane** form: ![The detail-pane edit form](img/detail-pane-edit.jpeg) - **Heading** — per language, required; the pane's title on the storefront. - **Heading Icon** — optional; **Upload a file** for a small decorative symbol beside the heading. - **CSS Classes** — optional styling hooks for a web developer; leave blank otherwise. - **Content** — the body, per language, in a full HTML editor (headings, lists, links, tables). 4. **Save**, and drag the rows in the list into the order the panes should appear on the page. ## What happens next The panes render on the product's detail page, below the product image and configure/buy buttons — here, a "Care & Materials" pane on the Shirt Configurator: ![A detail pane on the storefront](img/storefront-detail-panes.jpeg) ## Good to know - Panes belong to **one product**. Use **Copy** to reuse a pane's structure on another product, then repoint and re-edit it — the copies are independent. - Content is translatable: each active language gets its own tab in the **Content** editor, so the pane reads correctly in every storefront language. - Panes are informational only — they don't affect price or configuration. For choices that change the product, use [pages and questions](https://docs.configbox.at/docs/admin-guide/products/add-pages-and-questions) instead. --- # Set up the visual preview Page: https://docs.configbox.at/docs/admin-guide/products/set-up-the-visual-preview > **Audience:** store admins · **Scope:** product visualization (2D composite / 3D) · **Last reviewed:** 2026-07-20 **What this does** — Gives the configurator its most engaging feature: a product image that updates with every choice. Here is the demo Car doing it — the image is a stack of layers, one per selected answer: ![The Car configurator with its live 2D preview](./img/storefront-configurator.jpeg) ## Choose the visualization type On the product form, **Visualization → What type of visualization do you want to use?**: - **No visualization** — the configurator runs without a preview. - **Composite Image** — 2D layering: a **base image** plus one transparent overlay per selected answer. All you need is image files; this is the right choice for most products. - **ShapeDiver** — an interactive 3D model (rotate/zoom), driven by your questions. Needs a prepared model on the ShapeDiver platform; questions/answers bind to its parameters. ## Set up a 2D composite preview 1. **Prepare the artwork.** One **base image** (the product's constant part) and one overlay per answer that changes the look — all the **same pixel size**, overlays transparent (PNG) except for the part they change. Consistency of size and alignment is the whole trick. 2. On the **product**: set the visualization type to **Composite Image** and upload the **Base image of the product visualization**. 3. On each **answer** that changes the look: upload its **Visualization Image** and set the **Visualization Stacking Order** — higher numbers render on top. Give each *kind* of layer a consistent order band (paint 10, foil design 20, rims 30 …) so layers never fight. 4. Test on the storefront: click through the answers and watch layers swap. A layer that "jumps" is a size/alignment mismatch in the artwork; a layer hidden behind another needs a higher stacking order. Answers without a visualization image simply don't add a layer — only looks-changing choices need artwork. ### What the storefront actually assembles Worth knowing, because it explains most of what looks like a bug: - **The frame appears as soon as the type is Composite Image** — before you have uploaded anything. An empty gap beside the questions means the type is set and the artwork is not there yet, not that something is broken. - **The base image is optional.** Layers render over nothing at all, which is what you want for a product photographed against transparency. - **Only the answers currently selected contribute a layer.** Answers with no visualization image never add one, so you only need artwork for the choices that change the look. - **Layers are drawn in ascending stacking order** — lowest first, at the back. Two layers sharing a number keep whatever order the database returns them in, which is stable in practice and not worth relying on: give every layer its own number. ### File requirements The two uploads do **not** accept the same things, which catches people out: | | Formats | Maximum size | |---|---|---| | Product **base image** | JPG, PNG, GIF, TIF, BMP | 1 MB | | Answer **visualization image** | JPG, PNG **only** | 2 MB | So a GIF or BMP works as a base and is **refused** as an overlay. In practice overlays want PNG anyway — they need transparency — but the rejection message arrives at upload time and the reason is not obvious. Both live under the site's public data store, in `vis_product_images` and `vis_answer_images`. Back those up with the database; a restored database without them shows the frame and no artwork. ## Set up a 3D ShapeDiver preview 1. On the product: visualization type **ShapeDiver**, and select the **ShapeDiver model**. 2. On each question that drives the model: **Visualization → Controls a ShapeDiver parameter?** → pick the **parameter**. 3. On each answer of choice questions: set the **ShapeDiver choice value** the model expects when that answer is selected. Value questions (sliders, text) pass their entry directly. 4. Test live — the viewer updates with each selection. The division of labor: the *model* (built on ShapeDiver) defines what can vary; CBX just sends your customers' choices into its parameters. ## Good to know - The preview sits beside the configurator on every page; the **Visualization** block heading label is settable in **Settings → Block Headings**. - 2D overlays are lazy-loaded; enormous source images still cost bandwidth — export at the size you display. - Keep a copy of the layered source file (PSD or similar) — future answers need matching artwork, and re-alignment without the source is painful. - Copying a product copies its visualization setup and images. --- # Rules — conditional logic Page: https://docs.configbox.at/docs/admin-guide/rules/ > **Audience:** store admins · **Scope:** making the configurator dynamic · **Last reviewed:** 2026-07-20 **TL;DR** — A rule answers one yes/no question: *given the customer's current selections (and who they are), does this question or answer apply?* Attach rules to questions and answers and the configurator reshapes itself live — irrelevant options disappear or grey out, dependent questions appear, invalid combinations become impossible. ## Articles 1. **[Build a rule](https://docs.configbox.at/docs/admin-guide/rules/build-a-rule)** — the visual rule editor: conditions, operators, AND/OR, parentheses, show-if vs hide-if. 2. **[Control what happens on change](https://docs.configbox.at/docs/admin-guide/rules/control-what-happens-on-change)** — the companion settings: hide vs grey out, auto-selecting defaults, resolving selections that became invalid. 3. **[Rule recipes](https://docs.configbox.at/docs/admin-guide/rules/rule-recipes)** — ready-made patterns for the situations every configurator runs into. ## Where rules live - **On a question** — controls whether the whole question shows. - **On an answer** — controls whether that single choice is available within its question. No rule means "always show". The rule editor opens from the **Rule** section of the question or answer form. ## What rules can react to - **Answers to questions** — what the customer picked or entered elsewhere ("Answer in *Material* is *Oak*"). The everyday case. - **Results of calculations** — a computed number crosses a threshold ("Result of *Total span* is above 4") — this is how rules react to dimensions, weights and totals. - **Customer** — who is configuring ("customer-group field *is_trade* is 1") — for trade-only options and segment-specific behavior. - Stores with developer-built extensions may show additional condition tabs (e.g. **Custom Conditions**). --- # Build a rule Page: https://docs.configbox.at/docs/admin-guide/rules/build-a-rule > **Audience:** store admins · **Scope:** the rule editor · **Last reviewed:** 2026-07-20 **What this does** — Makes a question or answer conditional: it shows (or hides) only when the conditions you build here are met. Customers then only ever see valid, relevant choices. ## Before you start - Decide the sentence you want, in words: *"Show the **Engraving text** question if the answer in **Add engraving** is **Yes**."* If you can say it, you can build it. - The questions/answers the rule refers to must already exist. ## Steps 1. Open the question or answer, expand its **Rule** section, and click **Change**. The rule editor opens: ![The rule editor](./img/rule-editor.jpeg) 2. At the top, pick the rule's meaning: **Show the question if these conditions are met** or **Hide the question if these conditions are met** — whichever reads more naturally. 3. Build conditions from the **Condition Types** tabs: - **Answers to questions** — pick a question in the dropdown to see its draggable conditions (for a choice question: one per answer; for value questions: its entered value, and its price). Drag one into the rule area at the top. - **Results of calculations** — drag in a calculation's result to compare against a number. - **Customer** — conditions on the customer's group. 4. Set each condition's **operator** by clicking it: *is*, *is not*, *is below*, *is or below*, *is above*, *is or above* — and type the value to compare against where the condition takes one. 5. Combine multiple conditions by dragging in the **AND** / **OR** combinators (top right). To control precedence, select conditions and click **Put in parentheses** — e.g. `(Use is Indoor OR Use is Covered) AND Material is Steel`. 6. Housekeeping: **Remove selected** deletes marked pieces; **Limit condition width** compacts long chips for readability. 7. **Save** in the editor, then save the question/answer form. ## What happens next The rule evaluates live on every selection change. When it stops applying, the question/answer hides or greys out — and what happens to an already-made selection is governed by the [companion behaviors](https://docs.configbox.at/docs/admin-guide/rules/control-what-happens-on-change). ## Good to know - **Copy/paste**: the Rule section's buttons copy a whole rule between questions/answers — build once, reuse, adjust. **Delete** reverts to "always show". - Rules on **answers** are how you thin out a choice list per context; rules on **questions** remove whole inputs. - **Copying a product** re-points all rule references to the copy automatically — rules don't leak across products. - Rules re-evaluate on every change across the product; hundreds of deep rules can slow the configurator — keep conditions focused. - A rule only decides *visibility*. Requiring an answer stays with the question's "has to be answered" switch; prices stay with pricing. --- # Control what happens on change Page: https://docs.configbox.at/docs/admin-guide/rules/control-what-happens-on-change > **Audience:** store admins · **Scope:** the behavior fields that accompany a rule · **Last reviewed:** 2026-07-20 **What this does** — A rule only decides *does this apply right now*. The fields described here decide what the configurator **does** about it — so choices cascade smoothly instead of leaving customers with hidden-but-selected or suddenly-invalid answers. ## The settings, and when they matter All of these sit on the question form (the first also on answers), near the Rule section: - **What to do while the question is disabled** ("display while disabled") — when the rule is not met: **hide** the question/answer entirely, or show it **greyed-out** (visible, not selectable). Grey-out is good merchandising for options a customer could unlock with a different choice ("Reinforced frame — available with Steel"); hiding keeps the configurator short. - **What to do once the question gets enabled** ("behavior on activation") — when a question *becomes* applicable mid-configuration (a rule just started matching): leave it empty, or auto-select its default answer so the configuration is never incomplete at that moment. - **What happens if the current answer becomes impossible** ("behavior on inconsistency") — when the customer's current answer *becomes invalid* (its answer-rule stopped matching): deselect it, or replace it with the default/another valid answer. This is what prevents impossible combinations from surviving in the cart. - **What happens when the system changes a selection** ("behavior on changes") — whether such automatic corrections happen silently or the customer is **asked to confirm** first. Ask when a correction may surprise ("changing the material resets your color"); stay silent for obvious cascades. ![The four behavior fields on the question form, highlighted — they sit in the Rule section](./img/behavior-fields.jpeg) ## A worked example *Question "Color" is hidden while "Finish" is "Raw" (a hide-if rule). The customer picks Raw after already choosing a color:* 1. The Color question's rule stops applying → it hides (or greys out, per **Display while disabled**). 2. Its existing selection is now inconsistent → per **Behavior on inconsistency** it's deselected, so the color's price disappears from the summary. 3. Because **Behavior on changes** is set to confirm, the customer sees a prompt first and can back out of switching to Raw instead. ## Good to know - Defaults are the safety net: give every choice question a sensible **Default** answer so auto-activation and auto-replacement always have something valid to fall back on. - Test the flows on the storefront after wiring rules: click through the paths that toggle your rules and watch what appears, disappears and resets. Five minutes of clicking catches nearly everything. - Prices always follow the *actual current selections* — a deselected answer's price leaves the summary immediately; there is nothing extra to configure for that. --- # Rule recipes Page: https://docs.configbox.at/docs/admin-guide/rules/rule-recipes > **Audience:** store admins · **Scope:** common rule patterns, ready to adapt · **Last reviewed:** 2026-07-20 **What this does** — A cookbook. Each recipe names the situation, the rule to build, and the companion settings that make it feel right. Build them in the [rule editor](https://docs.configbox.at/docs/admin-guide/rules/build-a-rule); the wording matches its labels. ## 1. The dependent question *"Engraving text" should only appear when engraving was chosen.* - On the **Engraving text** question: **Show** if — *Answer in "Add engraving" is "Yes"*. - Companion: **Display while disabled = hide** (no point greying out a text box), and on the engraving question itself nothing else to do. ![Recipe 1 in the rule editor: show "Engraving text" if the answer in "Add engraving" is "Yes"](./img/recipe-1-dependent-question.jpeg) ## 2. Thin out choices that don't fit *Raw finish has no color choice; glossy and matte do.* - On the **Color** question: **Hide** if — *Answer in "Finish" is "Raw"*. - Companion: **Behavior on inconsistency = deselect**, **Behavior on changes = confirm** — a customer switching to Raw after picking a color is asked before the color resets. ![Recipe 2: hide "Color" if the answer in "Finish" is "Raw"](./img/recipe-2-thin-out-choices.jpeg) ## 3. The either/or bundle *Steel is only available for indoor or covered use.* - On the **Steel** answer: **Show** if — *(Answer in "Use" is "Indoor" OR Answer in "Use" is "Covered")*. - Multiple such answers? Put the rule on each steel-dependent answer, or reconsider the page order so "Use" is asked first. ![Recipe 3 on the "Steel" answer: show if "Use" is "Indoor" OR "Covered" — one bracket, one OR](./img/recipe-3-either-or.jpeg) ## 4. Upsell visibility (grey-out marketing) *Show the premium option to everyone, selectable only where it applies.* - On the premium answer: **Show** if — its availability condition. - Companion: **Display while disabled = grey out** — customers see what a different choice would unlock ("Reinforced frame — pick Steel to enable"). ![Recipe 4 on the "Reinforced frame" answer: show if "Material" is "Steel" — pair it with grey-out](./img/recipe-4-upsell-greyout.jpeg) ## 5. Trade-only options *Only trade customers may pick bulk packaging.* - On the **Bulk packaging** answer: **Show** if — *Customer group field … is …* (the Customer tab), matching your trade group's field. - Pair with [customer-group permissions](https://docs.configbox.at/docs/admin-guide/commerce/set-up-customer-groups) for the bigger buy-vs-quote split; use rules for option-level differences. ![Recipe 5 on the "Bulk packaging" answer: a Customer-tab condition on the customer group](./img/recipe-5-trade-only.jpeg) ## 6. React to size, weight or total (via a calculation) *Spans above 4 m need reinforcement.* - Build a calculation "Total span" ([how](https://docs.configbox.at/docs/admin-guide/pricing/build-a-calculation)). - On the **Reinforcement** question: **Show** if — *Result of "Total span" is above "4"* (the **Results of calculations** tab). - Companion: **Behavior on activation = select default**, so the reinforcement question never sits unanswered when it appears mid-configuration. ![Recipe 6: show "Reinforcement" when the result of calculation "Total span" is above 4](./img/recipe-6-calculation.jpeg) ## 7. Progressive disclosure for long configurators *Keep page 3 clean until the choices that matter are made.* - Give page-3 questions Show-if rules on the key earlier answers; combined with **Block continuing if selections are missing** (Settings/product), customers meet a short, relevant page instead of twenty greyed inputs. ## Working habits that pay off - **Say the sentence first** ("show X if Y is Z"), then build it — if the sentence needs "unless", you probably want Hide-if or parentheses. - **Put the deciding questions early** (page order), so rules cascade forward, not backward. - **Copy/paste rules** between similar answers, then adjust the value — faster and less error-prone than rebuilding. - **Walk the toggle paths on the storefront** after each batch of rules: flip the deciding answer back and forth and watch what appears, disappears, resets or prompts. --- # Store settings Page: https://docs.configbox.at/docs/admin-guide/settings/ > **Audience:** store admins · **Scope:** the store-wide configuration screens · **Last reviewed:** 2026-07-20 **TL;DR** — Three screens configure the store globally: **Settings** (one big, sectioned form of shop-wide switches), **Store Information** (your company identity, used on invoices, quotes and emails), and **Customer Fields** (which address/customer fields appear — and are required — in each flow). Languages and the custom-field labels live inside Settings too. > **Platform note (Magento 2):** only the **Settings** screen exists on Magento-hosted stores, > and it hides the sections that belong to CBX's own checkout (Magento owns cart, checkout > and emails there). **Store Information** and **Customer Fields** are hidden entirely, and > languages follow your Magento store views. See > [CBX on Magento 2](https://docs.configbox.at/docs/admin-guide/magento2/). ## Articles 1. **[Keep your store information current](https://docs.configbox.at/docs/admin-guide/settings/keep-store-information-current)** — the company identity behind invoices, quotes and emails. 2. **[Tailor the customer fields](https://docs.configbox.at/docs/admin-guide/settings/tailor-the-customer-fields)** — decide, per flow, what personal data you collect. 3. **[Tour the Settings sections](https://docs.configbox.at/docs/admin-guide/settings/tour-the-settings-sections)** — a closer look at Invoicing, Selection overview and Languages. 4. **[Manage API tokens](https://docs.configbox.at/docs/admin-guide/settings/manage-api-tokens)** — the access tokens external software presents to use your store's API. ## The Settings screen ![The Settings screen](./img/settings.jpeg) One form, collapsible sections — the ones you'll actually visit: - **Languages** — the shop's **active languages** (every translatable field gets one column per language) and the manager default. The **Currencies**, **Tax Classes**, **Salutations** and **Customer Groups** managers are embedded here for convenience. - **Checkout** — the default customer group and country, guest/registration behavior, the terms/refund-policy agreement gates, whether shipping exists at all (**Disable Shipping**), SKU display, and the newsletter preselect. - **Invoicing** — invoices on/off, when they generate (on order / after payment clearance / manual upload), email delivery, and the invoice number prefix/start. - **Reviews** — product reviews on/off and the moderation notification address. - **Configurator** — page tabs vs prev/next buttons, whether missing required answers block continuing, cart button placement, the default product image, weight unit, and the back-office-only "show internal names" helpers. Products can override the navigation options individually. - **Selection overview** — how detailed the live price summary is (overall, per page, per question, taxes, delivery/payment lines), separately for regular and recurring pricing. - **Custom Fields** — the **labels** for the free-form fields on products, questions, answers and other records; a labeled field becomes usable across forms, rules and calculations. - **Maintenance** — how long abandoned guest accounts and un-ordered carts are kept. - **Structured Data & Google Analytics** — SEO markup and e-commerce tracking. - **Analysis and Debugging** — minified assets, cache busting, performance profiling; only touch these when support asks. ## Store Information Your company identity: name, logo, address, contact details, bank account, VAT/registration data. These feed the placeholders on **invoices, quotations, emails and legal pages** — keep them current; a wrong IBAN here ends up on real invoices. ![Store Information](./img/store-information.jpeg) ## Customer Fields A matrix over every customer/address field: for each of the four flows — **Checkout, Quotation, Save Order, Profile** — you tick whether the field is **shown** and whether it is **required**. This is how you require the VAT number at checkout but not in the profile, or hide the phone field from quotations entirely. ![Customer Fields](./img/customer-fields.jpeg) ## Good to know - Most Settings entries take effect immediately on the storefront — change, reload, verify. - Feature-gating switches (shipping, invoicing, reviews, geolocation, analytics) hide whole areas of the admin/storefront when off — if a screen an article mentions is missing, check the corresponding switch here first. --- # Keep your store information current Page: https://docs.configbox.at/docs/admin-guide/settings/keep-store-information-current > **Audience:** store admins · **Scope:** the Store Information screen · **Last reviewed:** 2026-07-20 **What this does** — One screen holds your company's identity, and generated documents pull from it: **invoices, quotations, transactional emails and legal pages** all substitute these values into their placeholders. A typo here doesn't stay here — it ends up printed on customer paperwork. ![The Store Information screen](./img/store-information.jpeg) ## What's on it - **Identity** — shop name, website, and the **logo** used on PDFs. - **Address & contact** — the address block, sales/support phone and email, fax. - **Banking** — bank name, account holder, IBAN, BIC … — printed on invoices and shown for bank-transfer payment. **The IBAN customers wire money to comes from here.** - **Legal/registration** — VAT number, commercial register ID, company owner, legal venue — the imprint-style data legal pages and documents cite. - **Shop Description** — translatable descriptive text usable in templates and communications. ## When to touch it - **On day one** — the setup wizard fills the essentials; complete the rest before the first real order, especially banking and legal data. - **On any change** of address, bank account or contact details — the next generated invoice uses whatever stands here at that moment. ## Good to know - Already-generated invoices are **not** rewritten by later edits — they keep the data they were created with (as they should). Correct the data, then regenerate/re-release only where appropriate. - After editing, generate a test document — order something in a test run and download the invoice — to see the values in place. Layout oddities usually mean an overlong field, not a broken template. - The email addresses here are what customers see as contact points; the **sender** of transactional emails follows your site's mail configuration. --- # Manage API tokens Page: https://docs.configbox.at/docs/admin-guide/settings/manage-api-tokens > **Audience:** store admins · **Scope:** the API Tokens screen · **Last reviewed:** 2026-08-25 **What this does** — External software — an import script, a connected shop system, an AI assistant, an integration a developer builds for you — talks to your store through its API, and every one of those callers must present an **API token** to be let in. The **API Tokens** screen in the CBX menu is where you create tokens, decide exactly what each one may touch, see when each was last used, and shut one off when it should no longer have access. ## What a token may touch: the seven areas A token does not simply "have access". It has access to **areas** of your store, and for each area it can either **read** or **read and write**. The screen shows this as a grid — one row per area, a read box and a write box: | Area | What is in it | If a mistake happens here | |---|---|---| | **catalog** | What you sell: products, their pages, questions and answers, product lists, detail texts, examples, rules and price calculations. | Recoverable — a wrong title is a typo someone fixes. | | **store** | How you charge and deliver: settings, store details, currencies, tax classes, shipping, payment methods, notifications, countries. | Costly — a wrong tax rate is an invoice that already went out. | | **customers** | Your customers and their addresses, reviews and contacts. | Irreversible — personal data, once leaked, stays leaked. | | **orders** | Orders, quotes and payments — who bought what. | Irreversible — the same personal data, plus fulfilment. | | **conversations** | What visitors said to the AI advisor. | Irreversible — personal data in free text. | | **code** | Price calculations written as program code. Ticking this lets the caller put code on your server. | Dangerous — treat it like handing over the keys. | | **system** | The installation itself: updates, database housekeeping. | Costly — can stop updates; recoverable from a backup. | Three things to know about the grid: - **Write includes read.** A token that may write the catalog can also read it — you never need both boxes in one row. - **Rows are independent.** Ticking *orders* says nothing about *customers*. A token that works orders and needs to see who placed them gets both rows ticked. - **Every token can read the store row.** That box shows "always" and cannot be unticked: currencies, tax classes and shipping methods are the words everything else is written in, and a token that could not read them could not make sense of a single price. Secrets stored there — payment provider keys, the licence key — are never handed out, whatever the token holds. ## Create a token 1. Open **API Tokens** in the CBX menu and click **Add**. 2. **Name** the token after its holder — "Warehouse import", "Catalog assistant", "Agency staging" — so you can tell later which one to revoke. The name is for you; it grants nothing. 3. Choose its **scopes**. The quickest way is a **Start from** button above the grid — each one ticks the boxes for a common job: - **author** — build and maintain the catalog. - **fulfilment** — work orders, and see the customers they belong to. - **insights** — read the catalog and the advisor's conversations, to learn what visitors ask. - **operator** — store configuration and system housekeeping; no customer or catalog access. - **everything** — every row at write, **except code**. Then adjust the boxes by hand if the job is different. Grant only what the caller actually needs, and untick anything it does not. 4. **Code** is never part of a Start-from button. Tick it only when you are deliberately allowing someone to put program code on your server, and know who that is. 5. Optionally set an **expiry date** — the token stops working at the start of that day. Leave it empty for a token that never expires. 6. Click **Save and Close**. The screen now shows the new token **once**. **Copy it immediately** and hand it to whoever runs the calling software — it is never shown again, not even to you. The store keeps only a fingerprint, enough to recognise the token when it is presented but not to display it. If a token is lost before it was copied, there is nothing to recover: revoke it and create a new one. ## Watch and retire tokens The list shows every token with its scopes, expiry, creation date and — the column worth checking now and then — **Last used**. On a store with many tokens, the filter row narrows the list: search by **name**, or show only tokens carrying a given **scope** or only **revoked** ones. A token that has not been used in months probably belongs to something that no longer exists; retire it. - **Revoke** — open the token and set **Revoked** to Yes. The caller is shut out immediately. Revoking is **permanent**: a revoked token cannot be turned back on, only replaced by a new one. The row stays in the list, so you keep the record of what existed and when it was cut off. - **Remove** — deletes the row entirely. The token stops working just the same; you only lose the audit trail. Prefer revoking first and removing revoked leftovers later. ## If a token leaks Treat a token like a password: whoever has it can do whatever its scopes allow. If one ends up in the wrong hands — pasted in a ticket, committed to a code repository — **revoke it right away** and create a replacement for the legitimate caller. Revocation takes effect on the next request. ## Tokens created before the areas existed Older tokens were made with three broad permissions — read, write, admin. Updating the store translated each of them into the new grid without taking anything away: a former "read" token now reads every area, a former "admin" token writes the store, customers, orders and system rows, and a former "write" token writes the catalog **and has the code row ticked**, because that is what "write" used to allow. Open each of those tokens once and untick what its holder does not need — the code row first. ## Good to know - Tokens are for **software**, not people. Staff who work in the admin log in with their own account; a token never grants access to these admin screens. - The same token works for the store's API and for an AI assistant connected to the store; what it may do is the same in both places. - Creating a token does not change anything for shoppers — the storefront works entirely without tokens. - Expiry dates are a good habit for integrations run by outside parties: a token that ends by itself does not rely on anyone remembering to revoke it. - A developer with command-line access can create tokens there too, with the same areas and the same Start-from names; the result is identical. --- # Tailor the customer fields Page: https://docs.configbox.at/docs/admin-guide/settings/tailor-the-customer-fields > **Audience:** store admins · **Scope:** the Customer Fields matrix · **Last reviewed:** 2026-07-20 **What this does** — Controls exactly what personal data you collect, and when. For every customer/address field, you decide separately in each of four flows whether it is **shown** and whether it is **required** — so checkout can demand more than a quick quotation request, and the profile can stay lean. ![The Customer Fields matrix](./img/customer-fields.jpeg) ## How to read the matrix Each row is a field (company, salutation, name, address lines, ZIP, the country/state chain, VAT number, phone, language, newsletter …). The columns pair **show** and **require** for each flow: - **Checkout** — the buying flow (billing and delivery sections). - **Quotation** — the request-a-quote flow. - **Save Order** — saving a cart for later. - **Profile** — the account-editing screen. Tick *show* to render the field in that flow; tick *require* to block submission while it's empty. A field can be required at checkout, optional in the profile, and absent from quotations — that's the point. ## Steps 1. Go to **Customer Fields**. 2. Walk each flow column asking one question: *do we truly need this, here?* Every required field costs conversion; quotations especially deserve a short form (name + email often suffices — you're starting a conversation, not shipping a parcel). 3. **Save**, then run each flow on the storefront once to feel the result. ## Worked examples - **B2B store:** require *Company* and *VAT IN* at Checkout; show both, required, in Quotation; hide the salutation everywhere. - **Consumer store:** hide *Company* and *VAT IN* everywhere; require only name, address and email at Checkout; Quotation shows name + email only. ## Good to know - **Delivery-address fields** appear when the customer unticks "same as billing" — their show/require switches live in the same matrix. Whether the delivery block starts expanded is a **Settings → Checkout** switch. - The country → state → county → city dropdowns only offer **populated, active** geography records — if a state dropdown looks empty, that's the [geography screens](https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes), not this matrix. - **Salutation options** (Mr/Ms/…) are managed in the embedded Salutations manager in **Settings**; this matrix only decides whether the field shows. - Requiring the VAT number is what enables clean EU B2B reverse-charge handling — pair it with the country flags from [taxes](https://docs.configbox.at/docs/admin-guide/commerce/set-up-taxes). --- # Tour the Settings sections Page: https://docs.configbox.at/docs/admin-guide/settings/tour-the-settings-sections > **Audience:** store admins · **Scope:** every section of the Settings screen · **Last reviewed:** 2026-08-03 **What this does** — The [Settings](https://docs.configbox.at/docs/admin-guide/settings/) screen is one long form of collapsible sections holding the store-wide defaults. This article walks **all of them**, in the order they appear: what the section decides, the switches worth knowing, and where to read more. Anything set here is the *default* — many of these can be overridden per product. Open **Settings** in the CBX menu and expand the section you need: ![The Settings screen](img/settings.jpeg) ## Which section do I need? The sections fall into five jobs. Find your job, then jump to the section. ```mermaid flowchart TD Q["What are you changing?"] --> SELL["What the customer\nsees and does"] Q --> MONEY["Money and\npaperwork"] Q --> WORDS["Wording and\nlanguages"] Q --> HOUSE["Housekeeping"] Q --> TECH["Technical"] SELL --> S1["Configurator · Selection overview\nBlock Headings · Reviews"] MONEY --> S2["Checkout · Invoicing"] WORDS --> S3["Languages · Custom Fields"] HOUSE --> S4["Maintenance · License Key"] TECH --> S5["Connectors · Geolocation\nStructured Data · Analysis · AI Assistant"] ``` | Section | Decides | |---|---| | [Languages](#languages) | Which languages the store runs in | | [Checkout](#checkout) | How the cart and checkout behave | | [Invoicing](#invoicing) | Whether and when invoices exist | | [Reviews](#reviews) | Whether customers may review products | | [Configurator](#configurator) | How the configurator pages navigate and look | | [Block Headings](#block-headings) | The headings above the storefront blocks | | [Selection overview](#selection-overview-on-configurator-pages) | How detailed the live price summary is | | [IP Geolocation tracking](#ip-geolocation-tracking) | Guessing a visitor's country from their IP | | [License Key](#license-key) | Your CBX licence | | [Custom Fields](#custom-fields) | The labels of your own extra fields | | [Maintenance](#maintenance) | How long abandoned data is kept | | [Connectors](#connectors) | Payment and shipping connector setup | | [Structured Data and Google Analytics](#structured-data-and-google-analytics) | SEO markup and ecommerce tracking | | [Analysis and Debugging](#analysis-and-debugging) | Asset loading and profiling | | [AI Configurator Assistant](#ai-configurator-assistant) | The chat advisor on the storefront | ## Languages The shop-wide language setup: - The store's **active languages** — every translatable field (titles, headings, answers) then shows one input per language — and the **Shop Manager default language** for the back office. - For convenience, the **Currencies**, **Tax Classes**, **Salutations** and **Customer Groups** managers are embedded right here, so you can reach them without leaving Settings. ## Checkout How the cart and checkout behave, and what the customer is asked for. ![The Checkout section](img/settings-checkout.jpeg) | Setting | What it does | |---|---| | **Product List for continue shopping** | The product list customers return to from "continue shopping" links | | **Default Customer Group** | The group a brand-new customer lands in | | **Default Country** | The country assumed when detection fails or is unavailable | | **Secure Checkout** | Routes checkout over an encrypted connection (needs SSL on the server) | | **Disable Shipping** | Turns shipping off across the system — the shipping screens disappear with it | | **Show SKU in checkout record** | Shows product and option SKUs in checkout, notification emails and the order record | | **Preselect newsletter opt-in** | Ticks the newsletter box for the customer on every form | | **Show delivery address fields by default** | Expands the delivery address form; customers can choose "same as billing" to hide it | | **Show recurring customer login** | Offers a login form on quotation-request and save-order forms | | **Explicit agreement to terms** | Requires ticking the terms before an order can be placed | | **Explicit agreement to refund policy** | Same, for the refund policy | The two **explicit agreement** switches are the ones to check against your local consumer law before going live. ## Invoicing Controls whether and when invoices exist: - **Invoices on/off**, and **when they generate** — automatically **on order**, automatically **after payment clearance**, or **manually** (you upload the PDF). This choice decides which invoice actions appear on each order. - **Email delivery** — whether a released invoice is emailed to the customer automatically. - **Invoice numbering** — the **prefix** and the **starting number** for your invoice series. The mode you pick here is exactly what [process an order](https://docs.configbox.at/docs/admin-guide/orders/process-an-order) reacts to when it shows (or hides) the invoice buttons. ## Reviews Two settings: whether **customers may review products** at all, and the **email address** that is notified when a new review arrives. The product-level switch on each product form overrides the store-wide one, so you can allow reviews generally and suppress them on a single product. Reviews you receive are moderated on the **Reviews** screen. ## Configurator How configurator pages navigate and what they show. | Setting | What it does | |---|---| | **Show page navigation using tabs** | Page tabs above the questions | | **Show page navigation with next and previous buttons** | Next/previous buttons below the questions | | **Block continuing if selections are missing** | Disables next/finish while required questions are unanswered — overridable per product | | **Show cart button only on last page** | Keeps the cart button off the intermediate pages | | **Display conversion table** | A currency conversion table below the currency block | | **Default Product Image** | Used in lists wherever a product has no image of its own | | **Show internal question names in backend** | Useful when several questions share a title | | **Show internal answer names in backend** | The same, for answers | | **Weight Unit** | The unit shown wherever weights appear | The two **internal names** switches only change the *back office*. Turn them on while building a big configurator — telling three questions called "Colour" apart is much easier with their internal names visible. ## Block Headings The headings above the five storefront blocks — **Cart**, **Currencies**, **Navigation**, **Price Overview** and **Visualization**. Each is translatable, so you get one input per active language. Leave one empty to fall back to the built-in heading. ## Selection overview on configurator pages Controls how detailed the live **price summary** beside the configurator is — the running breakdown the customer watches while choosing. ![The Selection overview section](img/settings-selection-overview.jpeg) The section itself holds the settings that apply to both overviews: | Setting | What it does | |---|---| | **Overview to show first** | Which of the two overviews leads, regular or recurring | | **Show delivery option** | The delivery line in the summary | | **Show payment option** | The payment line | | **Show net in B2C mode** | Net amounts even in a gross-priced B2C store | Below it, **Regular Prices** and **Recurring Prices** repeat the same eight switches, so a subscription product can show its recurring breakdown at a different level of detail than its one-off prices — see [charge recurring prices](https://docs.configbox.at/docs/admin-guide/pricing/recurring-pricing): | Setting | What it does | |---|---| | **Show overview** | The overview as a whole | | **Show Prices** | Prices, as opposed to a plain list of selections | | **Show Configurator Pages** | Group the lines by configurator page | | **Expand Configurator Pages** | Whether those groups start open | | **Show questions** | The question titles | | **Show question prices** | A price per question | | **Show taxes** | The tax lines | | **Show cart button** | A cart button inside the overview | Turn detail up while you're testing pricing, down for a cleaner storefront. Products can also override the overview detail individually. ## IP Geolocation tracking Guesses a visitor's country from their IP so the store can preselect it. Choose the **Geolocation Service Type** — a **local file** or the **MaxMind web service** — and, for the web service, enter your **MaxMind User ID** and **License Key**. This only ever *preselects*; the customer can always change their country. ## License Key Your **License Key**, plus **License Manager Satellites** for multi-site licences. If CBX starts reporting licence problems after a domain change, this is the first place to look. ## Custom Fields CBX gives you spare fields on products, questions, assignments and answers. This section names them — a field stays hidden until you give it a label here. ![The Custom Fields section](img/settings-custom-fields.jpeg) | Slots | Where they appear | |---|---| | 6 product fields | The product form | | 4 question fields + a translatable one | The question form | | 4 assignment fields | Product-to-list assignments | | 6 answer fields | The answer rows | Label a field and it appears on that form; blank the label and it disappears again — the stored values are kept either way. Templates read these to print your own data on the storefront. ## Maintenance How long CBX keeps data that never turned into an order. ![The Maintenance section](img/settings-maintenance.jpeg) | Setting | What it does | |---|---| | **User Lifetime** | How long unregistered users without orders are kept | | **Unordered Orders Lifetime** | How long abandoned (unordered) orders are kept | | **Maintenance Intervals** | How often the cleanup runs | | **Old Alias Lifetime** | How long old URL aliases still redirect — set this to your search engine's re-indexing interval, 28 days if unsure | The first two are a housekeeping *and* a privacy control: they decide how long an abandoned cart with a visitor's data survives. ## Connectors The setup for **payment and shipping connectors** — each connector contributes its own settings here once it is enabled, so what you see depends on which connectors your store uses. ## Structured Data and Google Analytics Two related jobs, SEO markup and ecommerce tracking. | Setting | What it does | |---|---| | **Show Structured Data on Shop-Pages** | Emits product structured data for search engines | | **Where should the system show product structured data** | Which pages carry it | | **Use Google Analytics Ecommerce Tracking** | Basic ecommerce tracking | | **Property Tracking ID** | Your GA property | | **Conversion tracking for offline payments** | When an offline payment (bank transfer, invoice) counts as a conversion | | **Use Google Analytics Enhanced Ecommerce Tracking** | The richer enhanced-ecommerce events | ## Analysis and Debugging Asset loading and profiling. These are the switches to reach for when the storefront misbehaves after a customization. ![The Analysis and Debugging section](img/settings-debugging.jpeg) | Setting | What it does | |---|---| | **Enable profiling for selection XHR calls** | Times the calls the configurator makes on every selection | | **Use minified CBX Javascript files** | Serve minified JS | | **Use minified CBX Stylesheet files** | Serve minified CSS | | **Use assets cache buster query string** | Appends a version to asset URLs so browsers pick changes up | | **Loading method for requirejs** | How the script loader is attached to the page | Turning the two **minified** switches off serves the readable sources — the usual first step when a developer needs to debug the storefront. Turn them back on for production: minified assets are what your customers should be downloading. ## AI Configurator Assistant The chat advisor that helps visitors through the configurator. It needs an **Anthropic API key** before the panel appears at all. ![The AI Configurator Assistant section](img/settings-ai-assistant.jpeg) | Setting | What it does | |---|---| | **Enable the chat advisor** | Shows the panel on configurator pages and on the cart | | **Anthropic API key** | The key the store uses to reach the Claude API — it never reaches the browser | | **Model** | Smaller models are cheaper and faster; larger ones advise better | | **Model for the journal analysis** | Used for the lessons and Insights reports, which run rarely | | **Persona** | Neutral advisor, sales agent, or technical consultant | | **Greeting** | The panel's first message; empty means the default | | **House rules for the assistant** | Your own instructions — shop facts, what to emphasise, what never to promise | | **Assistant may add the configuration to the cart** | Off means it advises and selects, the visitor completes the purchase | | **Assistant may navigate the configurator** | Lets it switch pages and scroll to a question | | **Assistant may change the cart** | Lets it change a line's quantity, remove it, copy it or reopen it — the same things the cart's own buttons do. It always asks before removing | | **Messages per visitor per hour** | A lid on API spend | | **Keep the diagnostic journal** | Records conversations for the [Conversation Journal](https://docs.configbox.at/docs/admin-guide/ai-assistant/) | | **Also write the journal to a log file** | Mirrors each turn into a log file as well; off by default | | **Delete journalled conversations after (days)** | The journal stores what visitors typed — this is the retention limit | | **Analyse finished conversations** | Lets the scheduled task write the lessons-learned review | | **Contact name and email address** — for catalog & marketing, the product owner, the developer, the software vendor, and unhappy visitors | Who each group of the assistant's recommendations is sent to. Leave a group empty and nothing breaks; only its send button is disabled. See [Work the recommendations](https://docs.configbox.at/docs/admin-guide/ai-assistant/send-recommendations-to-your-team) | Two of these deserve a deliberate decision rather than a default. **The API key is a spending credential** — anyone holding it can spend on your account. And **the journal stores what visitors typed**, so the retention setting is a privacy decision, not just housekeeping. ## Good to know - Most Settings entries take effect immediately — change, reload the storefront, verify. - Feature switches (shipping, invoicing, reviews) **hide whole areas** of the admin and storefront when off; if a screen an article mentions is missing, check its switch here first. - On WordPress an extra **Wordpress URLs** section appears at the top, holding the URL segments for the cart and account pages. - Two related screens sit beside Settings: [Store Information](https://docs.configbox.at/docs/admin-guide/settings/keep-store-information-current) (your company identity on documents) and [Customer Fields](https://docs.configbox.at/docs/admin-guide/settings/tailor-the-customer-fields) (which personal data each flow collects). --- # CBX — Customization Guides Page: https://docs.configbox.at/docs/customization/ **How-to guides for extending CBX** through its upgrade-safe customization layer — one directory per install, resolved by `KenedoPlatform::p()->getDirCustomization()`. Its location is **per platform**: `data/customization/` inside the component on Joomla, `wp-content/plugins/configbox-customization/` on WordPress (a sibling of the plugin), and the `Rovexo_ConfigboxCustomizations` module's `view/customizations/` directory on Magento 2 — see the overview's §1.1 table. The guides write paths in the Joomla spelling (`data/customization/`); resolve `` against your platform's directory. Where `functional/` describes *what* the app does and `technical/` describes *how the current code is built*, this track is **task-oriented**: concrete recipes for adding your own behavior without modifying (and later losing) core component files. The customization layer is the supported extension point: files placed under `data/customization/` extend or shadow their core counterparts and survive component updates. (Exactly *how* each kind resolves — shadow, merge, register, or boot-time pre-emption, and which direction wins — varies per mechanism; the **overview** maps all of it.) It is **gitignored** in this repository (it is the developer's/integrator's local code), so these guides describe the structure and contracts you build against rather than checked-in examples. --- ## Start here - **[com_configbox_customization_overview.md](https://docs.configbox.at/docs/customization/customization_overview)** — **Overview & extension-point map.** The orientation guide: what the customization layer is, the one resolution rule that governs almost all of it (a customization path and a core path, one preferred over the other — which way depends on the mechanism), a table of *every* extension point with where it resolves in code, and a decision guide ("I want to change X → use mechanism Y"). Read this before the individual guides. **New extension points, and what changed under them:** [Latest features → platform & extensibility](https://docs.configbox.at/docs/features/latest/platform-and-extensibility) — the what's-new cut for integrators: site-specific CLI commands, question types the AI can operate, custom calc term types, payment connectors, on-screen help, and the move from a silent `false` to exceptions. [Latest features](https://docs.configbox.at/docs/features/latest/) is the whole track. ## Guides - **[com_configbox_overriding_views_and_templates.md](https://docs.configbox.at/docs/customization/overriding_views_and_templates)** — **Overriding views & templates.** The most common task: change a screen's markup via a template override (`templates//.php`), the three-slot template precedence chain, what variables a template has (`$this` is the view), the view-class vs. template precedence **asymmetry** (view classes are *not* "customization wins"), adding a brand-new view, and a worked example. - **[com_configbox_custom_properties.md](https://docs.configbox.at/docs/customization/custom_properties)** — **Creating custom Kenedo Properties.** End-to-end: how a `type` string resolves to your class + template, every lifecycle hook (request → validate → store → render → list → copy/delete) and when to override it, external storage, conditional applicability, attaching per-property CSS/JS, a complete worked `colorpicker` example, and a deployment checklist. - **[com_configbox_help_customization.md](https://docs.configbox.at/docs/customization/help_customization)** — **On-screen help.** Make the admin's help describe *your* install: append to (or `mode: replace`) any screen's note, add your own articles in a **Customizations** section of the guide, or shadow a shipped article by putting a file at the same path. One `help/` folder mirroring the guide's layout, images kept in the customization directory beside the file that uses them, nothing registered and no cache to clear. The counterpart to the fields you add — a customized form whose help still describes the stock screen is only half-delivered. - **[com_configbox_extending_stock_models.md](https://docs.configbox.at/docs/customization/extending_stock_models)** — **Extending stock models.** Add a field to (or tweak a field on) an existing model via `model_property_customization/` — the exact file/function/return contract, how the merge replaces vs. adds by `name`, the clone-then-change pattern for editing one core field, the migration that delivers the column, and a worked example. - **[com_configbox_overriding_controllers_and_models.md](https://docs.configbox.at/docs/customization/overriding_controllers_and_models)** — **Overriding controllers & models (behavior).** The precedence rule — **controllers, models, and view classes all load core-first (new-only)**, so the customization folders add *new* classes and don't shadow core ones — why changing an *existing* core class means `system_overrides/`, when to reach for that vs. observers vs. property injection, the `Cbcheckout→Configbox` legacy fallback, and worked examples. - **[com_configbox_custom_rule_conditions.md](https://docs.configbox.at/docs/customization/custom_rule_conditions)** — **Custom rule condition types.** Add a new "if…" to the Rule Editor: the `CustomCondition` naming/resolution contract, the three required methods (`getEvaluationResult` / `getConditionsPanelHtml` / `getConditionHtml`) and optional hooks, the `$selections` / `$conditionData` shapes and the `data-*`→`conditionData` bridge, performance notes (the evaluator is hot), and a worked `Weekday` example. (The engine is encoded; condition *types* are plaintext — no encoder needed.) - **[com_configbox_custom_question_types.md](https://docs.configbox.at/docs/customization/custom_question_types)** — **Custom question types.** Add a new kind of configurator input: why the **view folder** (`views/question_/`) is what registers the type in the admin dropdown, the optional `ConfigboxQuestion` class and its *silent* fallback to the base class, the five-step template chain, per-type admin fields via `model_property_customization/questions.php` and `appliesWhen`, and the composite-value trap (`floatval()` of a JSON selection is `0`). - **[com_configbox_question_types_and_ai.md](https://docs.configbox.at/docs/customization/question_types_and_ai)** — **Question types the AI understands and controls.** The companion contract that makes a custom type *self-describing*, so the chat advisor and every headless client can operate it like a stock type: designing the selection shape, canonical storage (`getStorableValue`), the comparison contract (`isSameSelection` / `isEmptySelection`), the AI descriptors (`getSelectionFormatHint` / `getSelectionSchema` / `getChoiceList` / `getConstraintHints`), sub-value delegation for rules and pricing, the frontend registration helper, the **reveal contract** for collapse/expand page flows, and how to pin it all in API specs. - **[com_configbox_custom_calc_term_types.md](https://docs.configbox.at/docs/customization/custom_calc_term_types)** — **Custom calc term types.** Add a building block to formula calculations — usually how a composite question type reaches a price: eager loading from `calc_term_types/`, the class-name suffix as a *stored* identifier, the three abstract methods (`getTermResult` / `getTermsPanelHtml` / `getTermHtml`), why `getTermResult` is hot, and the deleted-question guard that keeps a stale term from taking the formula editor down. - **[com_configbox_events_and_observers.md](https://docs.configbox.at/docs/customization/events_and_observers)** — **Events & observers.** React to (or augment/compute for) CBX events — the safest, additive extension point: how the dispatcher works and registers observers (before/after built-ins), the three event styles (react / by-reference augment / `returnLast` compute), the **two-part deployment** (file + `#__configbox_connectors` row), the **event catalog with signatures**, the `onOrderPlaced`-aren't-events trap, and a worked order-webhook example. - **[com_configbox_payment_connectors.md](https://docs.configbox.at/docs/customization/payment_connectors)** — **Payment (PSP) connectors.** Add a payment method as a convention-based **folder** (no base class): the customization-first folder resolution, the file contract (`administration.php` metadata functions, `settings.php` admin form, `bridge.php` checkout hand-off, `result.php` confirmation, `ipn.php` callback handler), the **IPN class-name quirk** (`Ipn`), IPN security, and a worked offline-method example. - **[com_configbox_assets_and_amd.md](https://docs.configbox.at/docs/customization/assets_and_amd)** — **Assets (CSS) & JavaScript (AMD).** Add CSS/JS with no build step: the auto-detected entry points (`custom.css`, `custom.js`, `custom_questions.js`), the `configbox/custom` AMD namespace, the server→client `appConfig` gateway, the view-asset engine (per-view/per-property CSS + `moduleId::method` init calls, XHR-safe), registering third-party libs via `cbGetCustomRequirePaths`/`cbGetCustomRequireShims`, and the min/cache-busting rules (don't `.min` your custom JS). - **[com_configbox_admin_ui_migration.md](https://docs.configbox.at/docs/customization/admin_ui_migration)** — **Admin UI migration (major release).** What changed in the backend form/list markup, CSS class names (the new `cb-*` prefix, Bootstrap 5 components, `.cb-content` scoping) and JS — and how to amend custom admin CSS/JS or template overrides. The stable `.trigger-*` (JS hooks) and `.property-*` (property styling) conventions that do **not** change. Maintained as each migration slice ships. - **[com_configbox_custom_cli_commands.md](https://docs.configbox.at/docs/customization/custom_cli_commands)** — **Custom CLI commands.** Add site-specific commands to the ConfigBox CLI suite under the reserved `custom` namespace (WordPress: `wp configbox custom `): the one-file contract (`cli/commands.php` returns name → `shortdesc`/`synopsis`/`callback`), the callback's args/options/exit-code interface, and the failure-isolation design — the file loads only when the `custom` dispatcher runs, so a broken commands file can never take down the stock commands. - **[com_configbox_language_overrides.md](https://docs.configbox.at/docs/customization/language_overrides)** — **Language overrides.** Change displayed UI text via `language_overrides//overrides.ini` (loaded last, wins): the **two-text-systems distinction** (INI/UI strings here vs. admin-authored content in `#__configbox_strings`), the load order, how to find a string's key, INI syntax gotchas, and per-language deployment. - **[com_configbox_system_overrides_and_boot_hooks.md](https://docs.configbox.at/docs/customization/system_overrides_and_boot_hooks)** — **System overrides & boot hooks (escape hatch).** Replace a framework/helper class that has no per-type loader, and run PHP at boot/DB-connect: how eager pre-emption beats the lazy autoloader (and its hard limit — the class mustn't already be loaded), the `_`-first load order, the boot-hook functions (`cbGetCustomRequirePaths`, `getPostDbConnectQueries`, …), the `getInitQueries.php` DB-connect hook, the `data/store/private/settings/` per-install slot, and the standing re-diff-after-update maintenance cost. The customization track now covers every supported extension point. Future additions would be incremental (new mechanisms introduced by the component) or deeper worked examples. ## Version migration - **Customization code migration to CBX 4** — now lives **inside the component** at [`../migration-to-cb4/`](https://docs.configbox.at/docs/migration-to-cb4/) so it ships with releases and reaches the WordPress/Magento 2 projects (all mount the same component repo). The running record of **breaking changes** in the CBX 4 refactor and how to realign your customization code — a dated breaking-changes log plus a playbook per affected customization kind (what the core auto-converts for you, and what you must edit by hand). Start here when a customization stops working after an update; it is **maintained as each CBX 4 slice ships**. --- ## Prerequisites Read `technical/com_configbox_kenedo_mvc.md` (§4, Kenedo Properties) first if the property-driven model is unfamiliar, and `technical/com_configbox_migrations.md` for delivering any DB schema a customization needs (the **customization migration track**, `data/customization/updates/`). ## Where customization code lives (quick map) Shown at its Joomla location; on WordPress the same tree sits in `wp-content/plugins/configbox-customization/`, on Magento 2 in `app/code/Rovexo/ConfigboxCustomizations/view/customizations/` (overview §1.1). ``` data/customization/ controllers/ ← add NEW controllers (core-first: does NOT shadow a core controller) models/ ← add NEW models (core-first: does NOT shadow a core model) views/ ← add NEW view classes (core-first: does NOT shadow a core view) templates/ ← override view templates / markup (customization-first) properties/ + tmpl/ ← custom Kenedo property types (+ form templates) model_property_customization/ ← inject/retune property defs on stock models (merge) question_types/ ← custom question type classes (ConfigboxQuestion) rule_condition_types/ ← custom rule condition types (CustomCondition) calc_term_types/ ← custom calc term types (CustomCalcTerm) custom_observers/ ← event observers (+ a #__configbox_connectors row) psp_connectors/ ← payment method connectors (folder per method) system_overrides/ ← replace a core class / boot hooks (escape hatch) language_overrides// ← overrides.ini — change UI text (loaded last) assets/ (css, javascript) ← custom CSS / AMD JS modules (configbox/custom) cli/commands.php ← custom CLI commands (`wp configbox custom `) updates/ ← customization-track DB migrations ``` For the precise resolution rule per mechanism (and the per-kind precedence asymmetries), see the **[overview](https://docs.configbox.at/docs/customization/customization_overview)**. --- # Admin UI Migration Guide (major release) Page: https://docs.configbox.at/docs/customization/admin_ui_migration **Who this is for:** developers with customization work on the CBX **admin (backend)** UI — custom CSS, custom admin JS, or overridden backend view/property templates. The upcoming **major release** modernizes the admin form & list markup, CSS and JavaScript, and **deliberately introduces breaking changes** to the admin HTML structure and CSS class names. This guide tells you exactly what changed and how to amend your customizations. If you only customize the **frontend** (configurator, cart, checkout, customer form), or you do not override admin templates / target admin CSS classes, you are very likely unaffected — but skim §1 to be sure. Read first: `com_configbox_customization_overview.md`, and — if you override templates — `com_configbox_overriding_views_and_templates.md`. For adding your own admin CSS/JS, see `com_configbox_assets_and_amd.md`. All paths are relative to the component root `docroot/components/com_configbox/`. > This guide is **updated as each migration slice ships**. The "Status" column below tells you which > slices are already in the code you have. A slice not yet marked *Done* has not changed anything yet. --- ## 1. What changed, in one minute The admin UI is rendered by the **Kenedo framework** (generic list + form templates, plus per-property field templates). The modernization does three things: 1. **Renames the structural CSS classes.** The old, inconsistent mix of prefixes (`kenedo-*`, `listing-*`, `configbox-*`, `backend-*`, `view-admin`) for the admin *chrome* (list table, detail form, toolbar, field groups) is replaced by a single, consistent **`cb-*`** prefix, and leans on **Bootstrap 5** component classes (`.table`, `.card`, `.btn`, `.alert`, `.pagination`, `.form-control`, …) wherever BS5 already provides the thing. 2. **Modernizes the HTML** to clean, semantic Bootstrap 5 markup (BS 5.3.8 is already bundled and scoped under `.cb-content`). 3. **Scopes all admin CSS under `.cb-content`** to stop CSS bleeding in from — and out to — the host CMS (Joomla/WordPress/Magento) and other extensions. ### Two conventions that DO NOT change — rely on them - **`.trigger-*` classes are stable.** They are the documented JS event-handler hooks. If your custom JS binds to `.trigger-…`, or your templates emit `.trigger-…` so CBX's JS picks them up, that keeps working. **Never** attach styling to `.trigger-*` — style with a `cb-*`/BS5 class instead. - **`.property-*` classes are kept.** The property-widget styling family (`property-name-`, `property-type-`, `property-label`, `property-body`, and the field-group inner names) is preserved, so property-level custom CSS and the `appliesWhen` visibility mechanism keep working. - **`data-*` attributes are preserved verbatim** (`data-record`, `data-properties`, `data-property-definition`, `data-key`/`data-value`, `data-task`, `data-init-calls-*`, etc.). So the breaking surface is essentially: **structural chrome classes renamed to `cb-*`, some HTML restructured, and custom CSS that was unscoped may need re-scoping.** --- ## 2. How to amend your customizations ### If you have custom admin **CSS** - Search your stylesheet for the old structural class names (see the map in §4) and update them to the new `cb-*`/BS5 equivalents. - If your rules were **unscoped** (bare `.kenedo-…`, `.view-admin …`), scope them under `.cb-content` to match the new baseline and win specificity battles against host-CMS CSS (e.g. `.cb-content .cb-list { … }`). Your `custom.css` still loads **last** (after `admin.css`), so you keep the final say. - Rules that target `.property-*` or `.trigger-*` generally need **no change**. ### If you have custom admin **JavaScript** - If you select elements by the old structural classes (`.kenedo-listing-form`, `.item-row`, `.kenedo-details-form`, …), update the selectors per §4. - If you bind to `.trigger-*` hooks or read `data-*` attributes, **no change** needed. ### If you **override** admin view or property templates - Overrides that emit the **generic** markup (list/form/field-group) must be re-synced to the new markup. The cleanest path for most overrides is to **re-base** them on the new stock template and re-apply your changes — see `com_configbox_overriding_views_and_templates.md` for the lookup order and technique. - Property-template overrides (`…/properties/tmpl/.php`) keep the `.property-*` contract; update only the inner control markup to BS5 where you had copied stock structure. --- ## 3. Migration slices — status & changelog | Slice | Area | Status | |---|---|---| | 1 | Generic **list** view (table, toolbar, filters, pagination, messages) | **In this build** | | 2 | Generic **form** view + field groups | **In this build** | | 3 | Property **field** templates (+ per-type JS/CSS extraction) | **In this build** | | 4 | Custom backend view templates (incl. rule/calc engine editors) | **In this build** | | 5 | Dependency swaps (modal, datepicker, select) — **admin only** | **In this build** | | 6 | CSS/JS consolidation & anti-bleed sweep | **In this build** | _Each slice's concrete renames/removals are appended below as it ships._ ### Slice 1 — Generic list view The backend **list** (data grid) markup, CSS and JS moved to `cb-*` / Bootstrap 5. The table now uses Bootstrap's `.table`, pagination uses `.pagination`, and messages use `.alert`. All list CSS is scoped under `.cb-content`. **Renamed (structural — update custom CSS/JS selectors and list template overrides):** | Old | New | |---|---| | `.kenedo-listing-form` | `.cb-list` | | `.kenedo-listing` (table) | `.cb-list-table` (+ `.table`) | | `.sortable-listing` / `.unsortable-listing` | `.cb-list--sortable` / `.cb-list--static` | | `.item-row` | `.cb-list-row` | | `.field-` (cells) | `.cb-cell-` | | `.kenedo-title-and-tasks` | `.cb-toolbar` | | `.kenedo-page-title` | `.cb-title` | | `.kenedo-after-title` | `.cb-after-title` | | `.kenedo-filters` / `.kenedo-filter` | `.cb-filters` / `.cb-filter` | | `.listing-filter` | `.cb-list-filter` | | `.kenedo-search` (filter button) | `.cb-list-filter-btn` | | `.listing-link` | `.cb-list-link` | | `.listing-data` | `.cb-list-data` | | `.kenedo-item-checkbox` | `.cb-item-checkbox` | | `.kenedo-check-all-items` | `.cb-check-all` | | `.sort-handle` | `.cb-sort-handle` | | `.kenedo-tasks` / `.kenedo-task-list` | `.cb-tasks` / `.cb-task-list` | | `.kenedo-pagination` | `.cb-pagination` | | `.kenedo-limit` / `.kenedo-limit-select` | `.cb-pagination-limit` / `.cb-pagination-limit-select` (+ `.form-select`) | | `.kenedo-pagination-list` | `.cb-pagination-pages` (+ Bootstrap `.pagination` / `.page-item` / `.page-link`) | | `.kenedo-hidden-fields` | `.cb-hidden-fields` | | `.kenedo-messages` / `.kenedo-messages-error` / `.kenedo-messages-notice` | `.cb-messages` / `.cb-messages-error` / `.cb-messages-notice` (+ `.alert` `.alert-danger` / `.alert-success`) | | task button `.btn-default` | `.btn-outline-secondary` | > **Messages** are shared list+form infrastructure driven by one JS function, so the `.kenedo-messages*` > → `.cb-messages*` rename was applied to **all** views that render a message block in this build > (not just lists). **Unchanged (rely on these):** `.trigger-*` JS hooks (incl. `.trigger-kenedo-list-task`, `.trigger-order-list`, `.trigger-change-page`, `.trigger-toggle-record-activation`), and the detail **form** wrapper `.kenedo-details-form` (migrates in Slice 2). All `data-*` attributes. ### Slice 2 — Generic form view + field groups The backend **detail form**, the **field groups** (collapsible fieldsets), the **property wrapper**, and the "item is in use" **usage block** moved to `cb-*`. The property *widget* identity classes are **kept** (see below), so `appliesWhen` visibility and per-property custom CSS keep working. **Renamed (structural — update custom CSS/JS selectors and form/group template overrides):** | Old | New | |---|---| | `.kenedo-details-form` (form wrapper / JS hook) | `.cb-form` | | `.kenedo-properties` (fields container) | `.cb-fields` | | `.kenedo-property` (single field wrapper) | `.cb-field` | | BS4 `.form-group` (was on every field wrapper) | _removed_ (use `.cb-field`) | | `.property-group` | `.cb-field-group` | | `.property-group-` | `.cb-field-group-` | | `.property-group-legend` | `.cb-field-group-legend` | | `.property-group-content` | `.cb-field-group-content` | | `.property-group-properties` | `.cb-field-group-body` | | `.property-group-notes` / `.property-group-notes-title` | `.cb-field-group-notes` / `.cb-field-group-notes-title` | | `.property-group-opened` / `.property-group-closed` | `.cb-field-group--open` / `.cb-field-group--closed` | | `.property-group-using-toggles` | `.cb-field-group--toggles` | | `.property-group-toggle-state` (hidden state input) | `.cb-field-group-state` | | `.kenedo-item-usage` | `.cb-item-usage` | | `.kenedo-usage-message` | `.cb-usage-message` | | `.kenedo-candelete-usage-entry-name` | `.cb-usage-entry-name` | | `.kenedo-candelete-usage-entry-link` | `.cb-usage-entry-link` | | `.kenedo-candelete-message` / `.kenedo-candelete-usage-entries` | `.cb-candelete-message` / `.cb-usage-entries` | | `.kenedo-hidden-fields` | `.cb-hidden-fields` | **Kept — do NOT change (the property-widget identity family):** - `.property-name-`, `.property-type-` — still on every `.cb-field` wrapper **and** on each `.cb-field-group`. The wrapper **`id` is still `property-name-`** (the field-group toggle and the `appliesWhen` visibility engine both read it). - `.property-label`, `.property-body`, `.invisible-field`, `.required`, `.required-flag`. - `.trigger-kenedo-form-task` (the form task-button hook), `.kenedo-new-tab` (open-in-new-tab hook), `.kenedo-datepicker` (migrates in Slice 5), all `data-*` attributes. > The `.property-*` widget internals (`.property-type-string` / `-dropdown` / `-file` / `-image` / > `-translatable` / `-multiselect` / `-published` / `-boolean` / … control markup) are **not** touched in > this slice — they migrate in **Slice 3 (property field templates)**. If you override a property template, > only the outer wrapper class changed (`.cb-field`); the inner control structure is unchanged for now. > **Scope note:** the 14 bundled payment-provider settings forms (`psp_connectors/*/settings.php`) and the > custom backend views that hand-roll a form shell (admincalculation, admincustomer, adminuserfields, > adminnotification, adminoptionassignment, adminorder, admincalccode, admincalcmatrix) were re-synced to > `.cb-form` / `.cb-fields` / `.cb-field` in this build as well, so nothing is left in a half-migrated state. ### Slice 3 — Property field templates + per-type JS/CSS extraction Two changes ship together: **(a) Per-type JS/CSS is now co-located with the property type**, not in the monolithic `admin.js`/`admin.css`. Each property type declares its own assets via the existing hooks on its `KenedoProperty` subclass: `getStyleSheetUrls()` (→ `assets/css/properties/.css`), `getJsInitCallsOnce()` / `getJsInitCallsEach()` (→ `assets/javascript/properties/.js`, an AMD module). The Kenedo view collects these and injects them on page load **and** on XHR view injection. This is the same mechanism `rule` / `calculation` / `groupPrice` already used. New stock modules: `translatable`, `datetime`, `dropdown`, `file` (shared by `image`), `multiselect`. New stock stylesheets: `translatable`, `dropdown`, `file`, `image`, `multiselect`, `boolean` (shared by `published`), `childentries`, `taxclassrates`, `shapedivermodel`, `shapedivergeometry`, `shapediverparameter`. **What this means for you:** if your custom admin JS/CSS targeted the *removed* code paths inside `admin.js` (`initHtmlEditors`, `initDatePickers`, the `.property-type-dropdown` branch of `initChosenDropdowns`) or the per-type rules that used to live in `admin.css`, those moved. To add behaviour/styling to a specific property type, prefer the same pattern: override the property class's `getStyleSheetUrls()` / `getJsInitCalls*()`. Your `custom.css` / `custom.js` still load last and keep the final say. **(b) Property-template inner classes renamed to `cb--*`** (the `.property-type-*` / `.property-label` / `.property-body` / `.trigger-*` contracts are unchanged): | Type | Old inner class | New | |---|---|---| | translatable | `translations` / `translation` / `translation-label` | `cb-translations` / `cb-translation` / `cb-translation-label` | | translatable | `language-switchers` / `language-switcher` | `cb-lang-switchers` / `cb-lang-switcher` | | translatable | `kenedo-translatable-textarea` / `translations.text-area` | `cb-translatable-textarea` / `cb-translations--textarea` | | translatable | `using-editors` (wrapper modifier) | `cb-using-editors` | | file / image | `file-wrapper` / `file-current-file` / `file-uploader` | `cb-file-wrapper` / `cb-file-current` / `cb-file-uploader` | | file / image | `file-delete(-checkbox/-label)` / `file-upload(-field)` / `file-link` | `cb-file-delete*` / `cb-file-upload*` / `cb-file-link` | | file / image | `highlighted` / `no-file-text` / `valid-extensions` | `cb-file-missing` / `cb-file-none` / `cb-file-valid-extensions` | | file / image | `show-file-uploader` / `file-upload-cancel` (JS hooks) | **`trigger-show-file-uploader`** / **`trigger-file-upload-cancel`** | | multiselect | `multiselect-toggles` / `extended-multiselect` | `cb-multiselect-toggles` / `cb-multiselect-extended` | | multiselect | `checkbox-field` / `checkbox-item` / `checkbox-label` (from `KenedoHtml::getCheckboxField`) | `cb-checkbox-field` / `cb-checkbox-item` / `cb-checkbox-label` | | shapedivergeometry / parameter | `sd-note-bad-geometry` / `sd-note-bad-parameter` | `cb-sd-note-bad-geometry` / `cb-sd-note-bad-parameter` | | shapediver* | `parameter-selection-help(-heading)` | `cb-sd-parameter-selection-help(-heading)` | **Kept (rely on these):** `.kenedo-html-editor` (platform-level TinyMCE hook), `.kenedo-datepicker` (jQuery-UI mount — the widget swap is Slice 5), `.radio-button-label` (shared with the frontend via `KenedoHtml::getRadioButtonField`), and all `.trigger-*` / `.property-*` / `data-*`. > **Not extracted this slice** (kept in `admin.css`, already view-scoped so no bleed): `paymentmethodparams` > (its inner control classes are emitted by encoded code) and `usergroupdiscount` (no plaintext property class > to hook). These render unchanged. ### Slice 4 — Custom backend view templates The admin views that hand-roll their own markup (instead of using the generic list/form) had their bespoke structural classes renamed to view-scoped `cb-*` prefixes, together with their paired CSS and JS. Each view family uses its own prefix; the `.trigger-*` hooks, `data-*` attributes, vendored library classes, and shared generic classes (`.key`, `.value`, `.active`, `.opened`, `.flash`, BS grid) are unchanged. | View(s) | Prefix | Examples | |---|---|---| | adminorder (order detail) | `cb-order-*` | `order-meta-info`→`cb-order-meta`, `order-overview`→`cb-order-overview`, `user-info-table`→`cb-order-info`, `admin-order-address`→`cb-order-address` | | admindashboard | `cb-dash-*` | `box`→`cb-dash-box`, `issue-item`→`cb-dash-issue`, `toggle-handle`→`cb-dash-toggle-handle`, `software-update`→`cb-dash-update`, `stat-*`→`cb-dash-stat-*` | | adminproducttree | `cb-tree-*` | `product-list`→`cb-tree-product-list`, `product-item`→`cb-tree-product`, `sub-list`→`cb-tree-sublist`, `sub-list-trigger`→`cb-tree-trigger`, `list-opened`→`cb-tree-open` | | adminmainmenu | `cb-menu-*` | `menu-list`→`cb-menu-list`, `menu-list-item`→`cb-menu-item`, `menu-link`→`cb-menu-link`, `sub-items`→`cb-menu-subitems` | | adminuserfields | `cb-userfields-*` | `user-fields-table`→`cb-userfields-table`, `userfield-`→`cb-userfield-`, `show-*`/`require-*`→`cb-userfields-show-*`/`-require-*` | | adminoptionassignment | `cb-optassign-*` | `option-data`→`cb-optassign-option`, `option-fields-target`→`cb-optassign-fields-target`, `xref-data`→`cb-optassign-xref` | | admincalculation / admincalccode | `cb-calc-*`, `cb-calccode-*` | `calc-type-subview`→`cb-calc-subview`, `name-type`→`cb-calc-name-type`, `calculation-code-notes`→`cb-calccode-notes` | | **Rule editor** (adminruleeditor*, condition classes, engine) | `cb-editor-*` (shared chrome), `cb-rule-*` | `picker-tabs`→`cb-editor-picker-tabs`, `drop-area`→`cb-editor-drop-area`, `operator-picker`→`cb-editor-operator-picker`, `rule-area`→`cb-rule-area`, `button-store`→`cb-rule-btn-store` | | **Calc formula editor** (admincalcformula*, calc-term classes, engine) | `cb-editor-*` (shared chrome), `cb-calc-*` | picker chrome shared with the rule editor; `button-limit-term-width`→`cb-calc-btn-limit-width`, term/parameter internals → `cb-calc-*` | | **Calc matrix** (admincalcmatrix) | `cb-matrix-*` | `calc-matrix`→`cb-matrix-table`, `matrix-wrapper-table`→`cb-matrix-wrapper`, `column-parameter`→`cb-matrix-column`, `input-value`→`cb-matrix-input`, `axis-parameter-picker`→`cb-matrix-axis-picker` | Also: the shared button utility `.backend-button-small` → **`.cb-btn-small`**; `.kenedo-page-title` (in the few custom views still using it) → **`.cb-title`**. > **Kept — do NOT change:** the vendored **dragtable** classes on the calc matrix > (`.dragtable-drag-handle`, `.dragtable-drag-boundary`, `.dragtable-col-placeholder`, …) are third-party > library API and are unchanged. All `.trigger-*` hooks (`.trigger-add-row`, `.trigger-add-column`, > `.trigger-remove`, `.trigger-edit-rule`, `.trigger-toggle-sub-items`, …), `.kenedo-popup*`, > `.kenedo-new-tab`, and the shared `.item`/`.bracket`/`.operator`/`.parameter`/`.input`/`.selected` calc-item > primitives are unchanged. > **Engine-editor note (releases):** the rule and calc editors' condition/term HTML is produced partly by the > **ionCube-encoded** rules/calc engine (`helpers/encoded/{13,14,15}/rules.php`, `calculation.php`). This > build renamed the classes in the plaintext engine sources too, so on a machine that runs the plaintext > engine (dev), the editors work immediately. **To ship, the engine must be recompiled** from the updated > plaintext sources — the class names in the encoded artifacts must match the new CSS/JS. > **Out of scope:** `adminorderslip` and the other PDF documents (quotation/invoice) are print artifacts with > their own isolated stylesheets (`pdf-orderslip.css` etc.), not admin chrome — left unchanged. ### Slice 5 — Dependency swaps (admin only) Three ageing widget libraries were replaced in the **admin** UI. The **frontend** (configurator, cart, checkout, customer form, calendar question) intentionally keeps the old libraries — this slice is scoped to the admin, like Slices 1-4. **1. jQuery Colorbox → Bootstrap 5 modal.** The `.trigger-open-modal` handler (`kenedo.js onOpenColorBoxModal`) now opens the target `href` in a Bootstrap 5 iframe modal (`.cb-iframe-modal`) instead of Colorbox. The `.trigger-open-modal` hook and its `data-modal-width` / `data-modal-height` attributes are unchanged. The `cbj.colorbox` AMD path and the Colorbox CSS block were removed. **2. jQuery-UI datepicker → native ``.** The **datetime** property (`properties/tmpl/datetime.php`) now renders a native date input (no `.kenedo-datepicker` mount, no calendar icon); the `configbox/properties/datetime` JS module was removed (native inputs need no JS). The **adminorders** date filters (`filter_startdate` / `filter_enddate`) are native date inputs too, and `admin.js` `initListFilterDatePickers` was removed. If you override `datetime.php`, note it is now a plain `input[type="date"]` (value normalised to `YYYY-MM-DD`). The frontend calendar question type keeps jQuery-UI. `.datepicker` class → `.cb-date-input`. **3. Chosen → Tom Select (Bootstrap 5 theme).** All **admin** ` ``` Key template rules, all visible above: bind the control's `name`/`id` to `$this->propertyName`; read the value from `$this->data`; honor `default`; escape everything with `hsc()`. The wrapper `
` and label are added by `getPropertyFormOutput()` — the template emits **only the body**. ### 4.3 Using it in a model Anywhere a model's `getPropertyDefinitions()` lists fields, add one entry: ```php $propDefs['color'] = array( 'name' => 'color', 'type' => 'colorpicker', // ⇒ your custom type 'label' => 'Accent color', 'default' => '#3366ff', 'positionForm' => 50, // order in the edit form 'positionList' => 8, // show as list column #8 (omit to hide from listing) 'required' => false, 'tooltip' => 'Pick the accent color shown on the product page.', ); ``` That single declaration now produces the form widget, the (optional) list column with the swatch renderer, request parsing + hex validation, the SELECT, and base-table storage — across every model that uses it. --- ## 5. The property definition reference (keys you can set) These keys are read by the base class and most properties. They live in the definition array, not your code. (Legacy aliases are auto-upgraded by `modernizeOldPropertySettings()`.) | Key | Effect | |---|---| | `name` | **Required.** Column / request key / data key. | | `type` | **Required.** The property type (resolves to your class + template). | | `label` | Form label and default list header. | | `labelList` | List header override (when different from the form label). | | `tooltip` | Adds a tooltip to the label. | | `default` | Default value for new records (read by templates). | | `required` | Enforced by the base `check()` (respects `applies()`). | | `invisible` | `true` adds the `invisible-field` class (hidden but present). | | `hideAdminLabel` | `true` suppresses the label row (`doesShowAdminLabel()`). | | `positionForm` | Sort order in the edit form. | | `positionList` | Sort order as a list column; **omit to keep the field out of listings**. | | `listCellWidth` | List column width. | | `canSortBy` | Make the list column sortable. | | `addSearchBox` | Add a search box for the column. | | `addDropdownFilter` | Add a dropdown filter (powered by `getPossibleFilterValues()`). | | `makeEditLink` | Wrap the list cell in the row's edit link. | | `appliesWhen` | Conditional applicability (§7). | | `options` | Space-separated flags → `optionTags` map (e.g. `ALLOW_HTML`, `USE_TEXTAREA`). | | `storeExternally` + `foreignTable*` | Store in a side table (§6). | Your own type can read any additional keys you like via `getPropertyDefinition('myKey', $default)` — e.g. the `string` type reads `stringType`, `unit`, `maxLength`. Document the keys your type understands at the top of its class. > **The per-type keys are catalogued.** Every shipped type's own settings — what `string`, `number`, > `image`, `join` and the rest read — are one article each under > `../technical/property-types/`, indexed by > `../technical/com_configbox_property_types.md`. Read the article for the type you are modelling > yours on; the shared keys above are only half the picture. > > (`size` was split in two because it meant a kilobyte ceiling on a file property and a `maxlength` > on a text one. It is now `maxFileSizeKb` and `maxLength`, with a shim routing the old key by type.) The **`options` / `optionTags`** mechanism is how flags are passed: `'options' => 'ALLOW_HTML USE_TEXTAREA'` becomes `$this->getPropertyDefinition('optionTags')['ALLOW_HTML'] === true`. Use it for boolean switches on your widget; reserve `ALLOW_HTML` / `ALLOW_RAW` for the request phase (they relax input sanitizing in the base `getDataFromRequest()` — only use them for trusted admin-only fields). --- ### Keys read by type generation and platform scope | key | meaning | |---|---| | `apiTitle` / `apiDescription` | The field's wording for somebody reading a **schema** instead of the admin form — they become `title`/`description` in the generated JSON schemas, the PHP record stubs and the TypeScript types. Both fall back to `label`/`tooltip`, so a field whose admin wording already reads correctly to a developer needs neither; give every *stored* property the pair on new work. Writing guidance: `../technical/com_configbox_property_definition_settings.md` §9. | | `platforms` | array of platform names the property APPLIES on (`joomla`, `wordpress`, `magento2`, `standalone`); absent = all. The property still exists everywhere — stored, readable, writable, one schema for every host. What this changes is presentation: elsewhere it is hidden in the form (`isVisible()` false, same as `invisible`) and can never be required (`isRequired()` false, so `platforms` overrides `required`). Emitted as `x-configbox-platforms` and stated in the field's description. | | `platformDefaults` | map of platform name → the value a NEW record starts with there, e.g. `array('magento2' => 0)`, overriding `default` on that host only. The column, its DB-level default and every existing row stay identical everywhere. Use it with `platforms` when a field is hidden on a host AND has to start at a different value there. Emitted as `x-configbox-platform-defaults`. | | `deprecated` | `true` marks the field deprecated in the schema (native keyword) and the record stub. | --- ## 6. Storing in a side table (`storeExternally`) If a property's data does not belong in the model's base table (e.g. one-to-many rows, or a value keyed by language/group), set it up for **external storage** and the base class does the JOIN, the read and the write for you: ```php $propDefs['spec_sheet'] = array( 'name' => 'spec_sheet', 'type' => 'mytype', 'label' => 'Spec sheet', 'storeExternally' => true, 'foreignTableName' => '#__configbox_product_specsheets', // side table 'foreignTableAlias' => 'specsheet', // alias used in the JOIN 'foreignTableKey' => 'product_id', // FK back to the base table key ); ``` With this, `getJoinsForGetRecord()` adds a `LEFT JOIN` on the side table (`:897`), `getSelectsForGetRecord()` selects from it, and the base `store()` does an upsert of `$data->{propertyName}` into the side table keyed by the base record's id, with proper `NULL` handling (`:322`). `getDataKeysForBaseTable()` returns `array()` so the value is *not* also written to the base table. Override `copy()`/`delete()` if the side data needs special cloning/cleanup beyond the single-row default. Use this when one column on a side table maps to one logical field. For genuine one-to-many grids, look at the [`childentries`](https://docs.configbox.at/docs/technical/property-types/childentries) type instead. > **The full mechanism is `../technical/com_configbox_property_types.md` §3** — including which types > support it (only `column`-kind ones; `derived` and `layout` types have no base-table column to > move), what happens on **delete** and **copy**, and the constraints your side table has to satisfy. > Two that catch people out: `foreignTableKey` must carry a **UNIQUE** index, because the write is an > upsert relying on the duplicate-key collision — without it you get a second row per save instead of > an update; and the base `delete()` **does** remove your side-table row when the record goes, so you > do not need an `afterDelete()` for that. --- ## 7. Conditional applicability — `applies()` and `appliesWhen` A property can be shown/validated only when other fields have certain values. Add `appliesWhen` to the definition and the base `applies()` (`:180`) evaluates it: ```php 'appliesWhen' => array( 'pricing_mode' => 'fixed', // applies only when pricing_mode == 'fixed' 'enabled' => array('1', '2'), // ... AND enabled is 1 or 2 'status' => array('!archived'), // ... AND status is not archived // '*' means "any non-empty value", '!*' means "still empty". ), ``` When a property does not apply, it is hidden in the form and skipped by required-validation. You normally do not override `applies()`; configure it through `appliesWhen`. **Negation is a leading `!`.** Within one key, plain values are alternatives (an IN list) and negated values are exclusions that all have to hold, so `array('!a', '!b')` reads as "neither a nor b". Mixing them means "one of the positives, and none of the negatives". > **Old notes say never to negate — that was true until 2026-08-12.** The two evaluators used > different sigils (`KenedoProperty::applies()` read a leading **`1`**, `assets/kenedo/kenedo.js` > a leading **`!`**), and PHP only negated single-value lists, so a negated condition behaved one > way in the form and the other in validation. Both sides now implement `!` with the same > semantics, and `1` is no longer a marker — `'enabled' => '1'` means "equals 1". See > `../technical/com_configbox_property_types.md` §1, which also records the one residual > difference (a `''` should-value against a record value of `'0'`). A property that is conditionally required must also not appear in an API's flat `required` list — it is not required for the other cases. See `../technical/com_configbox_property_types.md` §1. --- ## 8. Adding CSS and JavaScript to a property Properties can declare their own assets, loaded **only for views that actually contain the property** and **de-duplicated** across multiple uses. This works on both full page loads and XHR view injections (admin forms are frequently injected via XHR, not full reloads). The mechanism: the property returns asset references; `KenedoView` collects them from all its properties, merges them with the view's own, and emits them so the AMD loader (`assets/main.js`) wires them up. ### 8.1 Optional CSS — `getStyleSheetUrls()` Return an array of **full stylesheet URLs** (`KenedoProperty::getStyleSheetUrls()`, `:760`): ```php function getStyleSheetUrls() { return array( KenedoPlatform::p()->getUrlCustomizationAssets().'/css/properties/colorpicker.css', ); } ``` The view runs these through the same optimization pipeline as its own stylesheets (minified-variant lookup + cache busting) and injects them de-duplicated. Put the file under `data/customization/assets/css/properties/` (URL via `getUrlCustomizationAssets()`). Stock property CSS lives under the core `assets/css/properties/` dir for reference. Scope every selector to your property's wrapper class — `.property-type-colorpicker …` — so it cannot leak into other properties. ### 8.2 JavaScript — `getJsInitCallsOnce()` / `getJsInitCallsEach()` Return arrays of `"moduleId::method"` AMD strings: - **`getJsInitCallsOnce()`** (`:783`) — runs the **first** time a containing view is shown per page load. Use for document-delegated handlers (`cbj(document).on(...)`) and one-off setup that must not repeat on re-injection. De-duped globally. - **`getJsInitCallsEach()`** (`:805`) — runs **every** time a containing view is shown, including each XHR injection. The named method receives the injected view (a jQuery collection) as its only argument. ```php function getJsInitCallsEach() { return array('cbcustom/properties/colorpicker::initEach'); } ``` **Idempotency matters for `…Each`:** the same DOM can be processed more than once when a parent view is re-injected. Scope your work to the view and guard already-initialized nodes with a marker class: ```js // data/customization/assets/javascript/properties/colorpicker.js (AMD module 'cbcustom/properties/colorpicker') define([], function () { return { initEach: function (view) { view.find('.property-type-colorpicker:not(.cb-prop-initialized)') .addClass('cb-prop-initialized') .each(function () { // wire up this instance once }); } }; }); ``` The `moduleId` is free-form — point it at any AMD module id your customization registers (e.g. via `appConfig.customPaths`). Stock property modules live under `kenedo/properties/*` and `configbox/properties/*` for reference. There is no build step/bundler: CBX serves AMD modules directly (RequireJS), so a plain `define(...)` file is enough. --- ## 9. Deploying a custom property (checklist) A custom property is **customization-layer** code: it lives under `data/customization/` (gitignored, upgrade-safe — it is *not* overwritten by component updates), and the DB column it maps is delivered by a **customization migration**. ``` data/customization/ properties/ colorpicker.php ← the type class (KenedoPropertyColorpicker) tmpl/ colorpicker.php ← the form widget template assets/ css/properties/colorpicker.css ← optional CSS (getStyleSheetUrls) javascript/properties/colorpicker.js ← optional AMD module (getJsInitCalls*) updates/ .php ← migration: ALTER TABLE … ADD COLUMN color VARCHAR(7) … model_property_customization/ .php ← (optional) inject the definition into a stock model ``` Steps: 1. **Write the class** at `data/customization/properties/.php` with class `KenedoProperty` (see §2 for the naming rule — keep `` lowercase to avoid surprises). 2. **Write the template** at `data/customization/properties/tmpl/.php` (unless the property renders nothing or builds its own HTML in the class). 3. **Add the column** via a customization migration (`data/customization/updates/.php`), guarded with `ConfigboxUpdateHelper::tableFieldExists()`. Never `ALTER TABLE` by hand. See `technical/com_configbox_migrations.md`. 4. **Use the type** in a model: either a model you own, or inject the definition into a stock model via `data/customization/model_property_customization/.php` (the merge point is `KenedoModel::getCustomPropertyDefinitions()`). 5. **(Optional) Ship CSS/JS** under `data/customization/assets/…` and reference them from `getStyleSheetUrls()` / `getJsInitCalls*()`. 6. **Verify manually.** CBX has **zero automated tests** — load the admin form, save, check the listing, and (for XHR-loaded forms) confirm the widget works after injection, not just on full reload. --- ### Regenerate the types when your customization changes shapes Type generation bakes the **effective** definitions in — your `model_property_customization/` files and any models you ship under `data/customization/models/` included. After adding, removing or retyping a property, run ``` php cli/joomla.php configbox:generate-types ``` and commit the updated `generated/` artifacts together with the customization change. `configbox:generate-types --check` fails while they disagree, so a CI gate catches the forgotten run. Entities and fields your customization adds are marked (`x-configbox-origin`), so the diff reads as what it is. --- ## 10. Conventions & gotchas - **Override the minimum.** Every hook has a working default. A property that just needs a different widget is *one template file* + a thin class. - **Escape on output, sanitize on input.** SQL here is traditionally hand-built mysqli: `getQuoted()` backtick-quotes **identifiers**, `getEscaped()` escapes **values** (add the surrounding quotes yourself) — or bind values with `setPreparedQuery($sql, $params)` and skip manual escaping. In templates use `hsc()`; in `getDataFromRequest()` validate/normalize; never interpolate raw request data into SQL. - **Don't shadow a stock type by accident.** A file in `data/customization/properties/.php` replaces that built-in type install-wide. Use a fresh type name. - **Type-string casing.** Because the class name is `ucfirst(strtolower($type))`, keep type strings lowercase. CamelCase works only thanks to PHP's case-insensitive class names — don't rely on it in new code. - **`…Each` JS must be idempotent.** Guard with a marker class; the same DOM can be initialized repeatedly on re-injection. - **The column is the migration's job, not the property's.** A property maps an existing column; the schema change is a versioned, idempotent upgrade script. - **Match the surrounding style.** No namespaces, no PSR-4, static singletons, PHP templates — follow the existing Kenedo idioms rather than modern Joomla/PSR patterns. --- ## See also - `technical/com_configbox_property_types.md` — **the built-in type catalogue**: the settings every type accepts, the storage kinds, `storeExternally` (§3), and the type-selection table. One article per type under `technical/property-types/`. - `technical/com_configbox_property_definition_settings.md` — the storage keys (`dataType`, `nullable`, `unique`, `maxLength`) and §7 on declaring storage for a **custom** type. - `technical/com_configbox_kenedo_mvc.md` — the framework and the model/view loop (§4). - `technical/com_configbox_mvc_tasks.md` — the base tasks, including how `copy()` deep-clones property side data. - `technical/com_configbox_migrations.md` — delivering the DB column your property maps (core and customization tracks). - `external/kenedo/classes/KenedoProperty.php` — the base class; every overridable hook with its default. - `external/kenedo/properties/` + `…/properties/tmpl/` — ~30 worked examples (`string`, `boolean`, `note`, `join`, `file`, `groupPrice`, `rule`, …) to copy patterns from; each is documented in `technical/property-types/`. --- # Custom Question Types Page: https://docs.configbox.at/docs/customization/custom_question_types How to add your own **question type** to CBX — a new kind of input the configurator renders, with its own template, its own admin fields, and its own rules about what a selection means. CBX ships twelve types (`textbox`, `dropdown`, `radiobuttons`, `images`, `slider`, `calendar`, `upload`, …); this guide shows how to add one without touching core. Read `com_configbox_customization_overview.md` first, and `technical/com_configbox_configurator_questions.md` for how questions, answers and selections work underneath. All paths are relative to the component root `docroot/components/com_configbox/`; `getDirCustomization()` is `KenedoPlatform::p()->getDirCustomization()`, which resolves per platform (Joomla `data/customization/`, WordPress the separate customization plugin, Magento the `ConfigboxCustomizations` module). Source references are point-in-time — verify against the code. --- ## 1. The one thing to know first: the *view folder* registers the type A custom question type becomes selectable in the admin **because a view folder exists**, not because you wrote a class. `ConfigboxModelQuestions::getCustomQuestionTypes()` (`models/questions.php:1538`) simply lists folders: ```php $folder = KenedoPlatform::p()->getDirCustomization().'/views/'; $folders = KenedoFileHelper::getFolders($folder, 'question_'); // 'question_dimensions' -> choice 'dimensions' labelled 'Dimensions' ``` Those are merged into the `question_type` dropdown's choices (`models/questions.php:147`). So: ``` getDirCustomization()/views/question_dimensions/ ← this alone adds "Dimensions" to the dropdown view.html.php tmpl/ default.php ``` The label is `ucfirst()` of the folder suffix. **Nothing else registers a type** — no XML, no install step, no database row. Create the folder, and the type is offerable. --- ## 2. The class is optional — and it is where behaviour lives Rendering is the view's job; *meaning* is the class's. `ConfigboxQuestion::getQuestion()` (`classes/ConfigboxQuestion.php:111`) resolves one per question: ```php $className = 'ConfigboxQuestion'.ucfirst($questionData->question_type); // 'ConfigboxQuestionDimensions' ``` and looks for it in this order: 1. already declared (an autoloader or an earlier `require` got there first), 2. core `classes/question_types/.php`, 3. **`getDirCustomization()/question_types/.php`** — yours, 4. **no class found → plain `ConfigboxQuestion`**, silently. Point 4 is the trap worth internalising: a typo in the class name or filename does not raise an error. The type keeps working, with base-class behaviour, and every override you wrote is ignored. If your custom logic "does nothing", check this first. > **`getQuestion()` returns a `clone`.** State you set on the returned object is per-call and does > not persist to the next `getQuestion()` for the same id. Do not cache anything on `$this` > expecting it to survive. --- ## 3. The contract — what to override `ConfigboxQuestion` is a concrete class, not an abstract one: override only what your type needs. The methods that matter, grouped by job (`classes/ConfigboxQuestion.php`): ### The selection lifecycle | Method | Job | |---|---| | `onBeforeSetSelection(&$selection, $prevSelection, $cartPositionId)` | Last chance to normalise or reject a value **before** it is stored. `$selection` is by reference — rewrite it here | | `onAfterSetSelection($selection, $prevSelection, $cartPositionId)` | Side effects once stored (recalculate, clear a dependent question) | ### What a value *is* | Method | Job | |---|---| | `getStorableValue($selection)` | What goes in the database | | `getComparableValue($selection)` | What rules and calculations compare against — the numeric or scalar reduction | | `getOutputValue($selection = null)` | What a human sees: cart lines, order confirmations, e-mails | | `getSku($selection)` | The SKU the selection stands for, frozen onto the order line. Base: the picked answer's `sku`, else `NULL` | | `getInitialValue()` | The value a fresh configuration starts with | | `getRawValue()` | The unprocessed stored value | ### Giving the order line a SKU — `getSku($selection)` `getSku()` is the one to override if your type is *ordered* rather than merely configured. The base implementation knows exactly one source, the picked answer's `sku` column, so an **answer-taking** type needs nothing from you. A **free-entry** type has no answer record to read: without an override it returns `NULL` and the order line freezes an empty SKU, however precisely the selection describes a real part. ```php class ConfigboxQuestionDimensions extends ConfigboxQuestion { /** * '{"w":"1200","h":"800","q":"2"}' -> 'PANEL-1200-800' */ public function getSku($selection) { if ($selection === null || $selection === '') { return null; } $data = json_decode($selection, true); if (empty($data['w']) || empty($data['h'])) { return null; } return 'PANEL-'.intval($data['w']).'-'.intval($data['h']); } } ``` Four rules, all of them things the caller relies on: - **Return `NULL`, never `''`,** when the selection stands for no SKU. The caller casts (`(string) $question->getSku(...)`), so `NULL` and `''` land in the database identically — but only `NULL` lets a sub-class of *your* class tell "no SKU" from "an SKU that is the empty string", and it is what the base implementation returns. - **Work from the `$selection` you are given**, not from `ConfigboxConfiguration::getInstance()->getSelection()`. Unlike `getOutputValue()` the parameter is required and never means "go and look it up" — the order record calls this while freezing a *cart position's* stored value, which is not necessarily the live configuration. - **Decode composite values yourself.** Same trap as the rest of the value group: a JSON selection is a string to the base class. - **Don't assume it is called once per order.** Treat it as a pure function of the selection; do no writes, and keep it cheap. Core calls it in exactly one place: `ConfigboxModelOrderRecord::createOrderRecord()`, which freezes the result into `#__cbcheckout_order_configurations.option_sku` for every selection on the position. That column is what the order overview, the notification e-mails and the shop-manager screens print when the `sku_in_order_record` setting is on, and what an ERP or fulfilment integration reads off the order. It is a **freeze**: the value is captured at checkout, so changing your derivation later moves new orders only — past orders keep the SKU they were placed with, by design. **Composing a whole product code from getSku()** — the pattern for a live "configuration code" (catalogue number) that assembles as the customer configures. Because `getSku()` is a method of the *type*, one composer can walk every question of the product without knowing any type's internals: load each question via `ConfigboxQuestion::getQuestion()`, skip the ones that do not `applies()` or whose selection `isEmptySelection()`, collect the non-empty `getSku($selection)` values in catalogue order (page ordering, then question ordering), and join. Stock answer questions contribute the picked answer's `sku` column through the base implementation, so the composer works for mixed products for free. Two seams make it live: render the composed code server-side in a **page-layout template** (see `com_configbox_overriding_views_and_templates.md`), and append it to every selection response through the **`postMakeSelection(&$response)`** hook (see `com_configbox_overriding_controllers_and_models.md`), which a small JS module reads off the `serverResponseReceived` event. Because the code bar, the responses and the order-line freeze all read the same `getSku()`, they can never disagree. Worked example: the Beta Calco configurator in the cbx-joomla site customization (`lib/BetacalcoCode.php` + `templates/configuratorpage/betacalco.php` + `system_overrides/postMakeSelection.php`). ### Validation | Method | Job | |---|---| | `isValidValue($value)` | The gate. Return false to reject | | `getMinimumValue()` / `getMaximumValue()` | Bounds, if the type has them | | `isValueTooLow($value)` / `isValueTooHigh($value)` | Bound checks, if "too low" is not a plain `<` | | `getValidationMessage($limitValue, $tooHigh = true)` | The message the customer reads | ### Money and weight **Do not override `getPrice()` / `getPriceRecurring()` / `getWeight()` — they are not consulted.** The methods exist on the base class as thin delegates, but every real consumer (the question view's price display, the stock QuestionProperty rule condition and calc term) calls the `ConfigboxPrices` statics directly, so an override on your type class changes nothing anywhere that matters. And the static per-answer path prices a selection only when it is a bare answer id (`$question->answers[$selection]`) — a composite JSON selection prices at **0**, silently. A type whose price depends on its value (per foot, per quantity, per m²) is priced by assigning a **formula calculation to the question's `calcmodel`**, built from a custom calc term that reads the selection through the type's own sub-value semantics — see `com_configbox_custom_calc_term_types.md`. That runs inside CBX's engine on every path (display, cart, order freeze). Weight works the same way through `calcmodel_weight`. **A composite type overrides most of the "what a value is" group.** If your selection is JSON — a width/height/quantity triple, say — the base class cannot do anything sensible with it: `floatval()` of a JSON string is `0`, so comparisons, prices and validation all silently see zero until you decode it yourself. --- ## 4. The template chain `ConfigboxViewQuestion::renderView()` (`views/question/view.html.php:362`) tries five paths in order and uses the first that exists: | # | Path | Use | |---|---|---| | 1 | platform template override for `com_configbox` / `` | A site template overriding your type | | 2 | `getDirCustomization()/templates//