# Frontend User Stories

> What a customer can do in a CBX storefront, told as user stories and organized by epic — from browsing the catalog through configuring, buying, and managing …

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

---
What a customer can do in a CBX storefront, told as user stories and organized by epic — from
browsing the catalog through configuring, buying, and managing orders. Each story follows
"As a … I want … so that …", with acceptance notes where they add something.

**Personas**

- **Visitor** — not logged in, browsing.
- **Shopper** — actively configuring or buying (guest or registered).
- **Guest** — checks out without registering up front; an account is created along the way.
- **B2B buyer** — belongs to a business customer group (net prices, possibly quotations).
- **Customer** — registered user with order history.

The overall journey the epics walk through:

```mermaid
flowchart LR
    A["Browse the listing"] --> B["Product detail page"]
    B -->|"configurable product"| C["Configure step by step"]
    B -->|"simple product"| D["Cart"]
    C --> D
    D --> E["Checkout"]
    E -->|"pay now"| F["Payment provider"]
    E -->|"B2B buyer"| G["Request a quote"]
    F --> H["Confirmation, invoice, order history"]
    G --> H
```

---

## Epic 1 — Browse & Discover

**US-1.1 — View the product listing**
As a visitor, I want to see a grid of products, so that I can find something to configure or buy.
- Each tile shows image, title, price block, and — when reviews are enabled — star rating and
  review count.
- Products appear alphabetically or in an admin-defined order.

**US-1.2 — Open a product detail page**
As a visitor, I want to open a product's detail page, so that I can read its description, price
and reviews before deciding.
- Shows title, image, price (regular and/or recurring, was-price, or custom price text) and the
  long description. Optional detail panes (tabs or accordion) and reviews with an aggregate
  rating appear when set up.
- Description text can embed live placeholders such as `{productprice}` and `{linkconfigure}`,
  so prices and buttons in the copy stay current.

**US-1.3 — Start configuring**
As a shopper, I want to click "Configure" on a configurable product, so that I can build my own
version. The button leads straight into the configurator's first page.

**US-1.4 — Buy a simple product directly**
As a shopper, I want to add a non-configurable product straight to the cart, so that I can buy
it without going through a configurator.

---

## Epic 2 — Configure a Product

The configurator presents one product as a series of pages; each page asks questions, and most
questions offer answers to pick from. This structure is what the admin builds, and it is what
the shopper walks through:

```mermaid
flowchart TD
    P["Product"] --> Pg["Pages — the steps, shown as tabs"]
    Pg --> Q["Questions — what the shopper decides"]
    Q --> A["Answers — the selectable options"]
```

**US-2.1 — Move through the configurator step by step**
As a shopper, I want to navigate between configurator pages via tabs and prev/next buttons, so
that I can work through the configuration at my own pace.
- The browser's back/forward buttons work as expected.
- If the admin enables it, navigation is blocked while required selections on the current page
  are still missing.

**US-2.2 — Answer each question in the format that fits it**
As a shopper, I want every question presented in a control suited to what's being asked, so that
choosing is quick and natural. Question types include:
- Single choice as a dropdown or radio buttons; on/off features as a checkbox.
- An image grid for visual selection (single- or multi-select), with images lazy-loaded.
- Predefined values with the option to type a custom value instead.
- Free text (textbox or textarea), optionally with a unit suffix — e.g. an engraving.
- A slider synced to a number field, within admin-defined min/max/step.
- A localized calendar for dates, with day-range limits.
- A free color picker, or a standardized RAL color chosen from a swatch catalog.

**US-2.3 — Upload a file**
As a shopper, I want to drag-and-drop or browse to upload a file, so that I can attach my own
artwork or documents to the configuration.
- A progress bar shows during upload; the file appears as a download link in the cart and order.
- Files outside the allowed extensions, types or size are rejected with a clear message.

**US-2.4 — See the price update live**
As a shopper, I want the price breakdown to update immediately after each change, so that I
always know the current cost without reloading.
- Shows regular and recurring totals, per-question and per-page lines, tax, delivery and
  payment. B2C shoppers see prices including tax; B2B buyers see net prices with tax listed
  separately.

**US-2.5 — See a live visualization of my configuration**
As a shopper, I want the product to update visually as I select options, so that I can preview
what I'm building.
- 2D visualization stacks layered images that show or hide per selected answer; 3D visualization
  drives an interactive ShapeDiver viewer whose parameters follow my selections.

**US-2.6 — Only be shown choices that apply (rules)**
As a shopper, I want questions and options that don't fit my other choices to be hidden or
greyed out, so that I can't wander into invalid territory.

**US-2.7 — Get help resolving conflicting selections**
As a shopper, I want to be warned — and offered an automatic fix — when a selection becomes
inconsistent with my other choices, so that I can't build an invalid product.
- Newly activated questions get sensible defaults; changes that would conflict prompt me to
  confirm.

Every change flows through the same live loop — no page reloads anywhere:

```mermaid
flowchart LR
    S["Shopper changes a selection"] --> R["Rules re-evaluate"]
    R --> V["Questions and options show, hide or grey out"]
    S --> P["Prices recalculate"]
    P --> B["Price breakdown updates"]
    S --> Z["Visualization updates"]
```

**US-2.8 — Be told what's still missing**
As a shopper, I want to see which required selections are missing before I can add to cart, so
that my configuration is complete.
- Adding to cart with an empty required field shows an inline message on that specific field
  ("Please make a selection in this field.") and blocks the add — per-field feedback, not just
  a global error.

**US-2.9 — See options that aren't available yet**
As a shopper, I want options outside their availability window shown as disabled with an
"Available on <date>" note, so that I know they exist and when I can choose them.
- Driven by the option's availability date together with its "disable when not available"
  setting.

**US-2.10 — Resume an in-progress configuration**
As a shopper, I want my configuration saved automatically as I go, so that I can come back and
continue where I left off. Selections persist for the whole session without any explicit save.

**US-2.11 — Add the finished configuration to the cart**
As a shopper, I want to add my completed configuration to the cart, so that I can proceed toward
buying it.
- Alternatively I can add it and immediately start another configuration based on it — handy for
  building a set of near-identical variants.

---

## Epic 3 — Cart

**US-3.1 — Review the cart**
As a shopper, I want to see all my cart positions with prices, discounts, subtotal, delivery,
payment fee, tax per rate and grand total, so that I understand exactly what I'll pay.

**US-3.2 — Get my agreed pricing automatically**
As a B2B buyer, I want customer-group volume discounts applied without asking, so that the cart
always reflects my negotiated terms.

**US-3.3 — Manage cart positions**
As a shopper, I want full control over each position, so that the cart ends up exactly right:
- **Edit** — re-open a configured position in the configurator and change selections.
- **Copy** — duplicate a position with all its selections, then tweak the copy.
- **Remove** — drop a position I changed my mind about.
- **Change quantity** — order more than one, with totals recalculated.

**US-3.4 — Keep an eye on the cart while browsing**
As a visitor, I want a compact mini-cart (quantities, titles and totals) visible across pages,
so that I can track my cart without leaving what I'm doing.

**US-3.5 — Switch currency**
As a visitor, I want to switch the display currency, so that I see prices in my own currency,
converted at the shop's configured exchange rate.

---

## Epic 4 — Checkout

**US-4.1 — Check out on a single page**
As a shopper, I want to proceed from cart to a single checkout page, so that completing the
purchase is one coherent step.

**US-4.2 — Enter billing and delivery addresses**
As a shopper, I want to enter my billing address and, if different, a separate delivery address,
so that the order is billed and shipped correctly.
- Which fields appear (and which are required) is admin-configurable — company, salutation,
  names, address lines, zip, country/state/county/city, VAT-IN, phone, language, newsletter.
- EU VAT-INs are validated against the official VIES service where applicable.

**US-4.3 — Not have to register first**
As a guest, I want an account created and logged in automatically when I enter my address, so
that I never face a separate registration wall. My email address becomes my username.

**US-4.4 — Choose a delivery method**
As a shopper, I want to pick from delivery options valid for my country and order weight, so
that I can trade off shipping speed against cost. Each option shows its price and tax.

**US-4.5 — Choose a payment method**
As a shopper, I want to pick a payment method available for my country and customer group, so
that I can pay how I prefer. Any surcharge is shown before I commit.

**US-4.6 — Accept terms and refund policy**
As a shopper, I want to read and accept the terms and refund policy when the shop requires it,
so that the order is legally complete. The checkboxes are enforced only when the corresponding
settings are on.

**US-4.7 — Place the order**
As a shopper, I want to place my order, so that it's submitted and I can pay. The order is
re-validated server-side before it's accepted.

**US-4.8 — Pay via my chosen payment provider**
As a shopper, I want to complete payment through the provider I picked, so that payment happens
securely on their infrastructure.
- Redirect providers receive the amount, currency, order reference and return URLs
  automatically; token-based gateways (e.g. Stripe) charge server-side without a redirect.

**US-4.9 — See a confirmation**
As a shopper, I want a thank-you page after paying, so that I know the order went through — with
links to the order status and my account.

---

## Epic 5 — Orders, Invoices & Post-Purchase

**US-5.1 — Have payment confirmed automatically**
As a customer, I want my order marked paid as soon as the payment provider confirms it, so that
nothing depends on me (or the shop staff) doing anything manually.

**US-5.2 — Receive a PDF invoice by email**
As a customer, I want a PDF invoice emailed to me when my order is paid, so that I have a record
for accounting.

**US-5.3 — Download my invoice any time**
As a customer, I want to download my invoice from my account or order page, so that I can
retrieve it whenever I need it. Invoices are only accessible to their owner.

**US-5.4 — View my order history**
As a customer, I want a list of my past orders with status and details, so that I can track and
review my purchases.

**US-5.5 — Save a cart for later**
As a shopper, I want to save my current cart, so that I can come back and complete it another
day.

---

## Epic 6 — Request a Quote

**US-6.1 — Request a quotation instead of buying**
As a B2B buyer, I want to request a formal quote for my configuration instead of paying
immediately, so that I can get pricing and approval first. Whether quoting is offered is
controlled per customer group.

**US-6.2 — Receive the quote the way my account is set up for**
As a B2B buyer, I want to download the quote PDF, get it emailed, or be told the sales team will
follow up — whichever my account is configured for.

**US-6.3 — Submit a quote request as a new contact**
As a visitor, I want to submit a request-for-quote with my details and a free-text comment, so
that the shop can prepare a custom offer (optionally registering me in the process). A thank-you
page confirms how I'll receive the quote.

**US-6.4 — Turn an accepted quote into an order**
As a customer, I want to check out a previously requested quotation from my order page, so that
an accepted quote becomes a real purchase without reconfiguring anything.

---

## Epic 7 — Account & Profile

**US-7.1 — Register an account**
As a visitor, I want to register with my name, email and password, so that I can track orders
and check out faster.

**US-7.2 — Log in and pick up where I left off**
As a customer, I want to log in, so that I can access my orders, addresses and saved carts.
Anything I did as a guest — cart, orders — is migrated into my account on login.

**US-7.3 — Reset my password**
As a customer, I want to reset my password via an emailed verification code, so that I can
regain access if I forget it.

**US-7.4 — Manage my profile and addresses**
As a customer, I want to view and edit my profile, billing and shipping addresses, so that
future orders use the right details. Which fields appear is admin-configurable per context.

**US-7.5 — Get a permanent account just by buying**
As a shopper who hasn't registered, I want a permanent account created for me automatically when
I complete a purchase, so that I can log back in afterward to see my orders and invoices.
- Note: until then, an in-progress or abandoned configuration is tracked behind the scenes on a
  temporary record that housekeeping later cleans up — the shopper never sees this.

**US-7.6 — Control newsletter opt-in**
As a customer, I want to opt in or out of the newsletter during checkout and registration, so
that I decide what marketing I receive.

---

## Epic 8 — Reviews

**US-8.1 — Read product reviews and ratings**
As a visitor, I want to read star ratings and review comments on a product, so that I can judge
it before buying.

**US-8.2 — Submit a review**
As a customer, I want to submit a star rating and comment for a product I bought, so that I can
share genuine feedback.
- Submitted reviews are held unpublished for admin moderation, and the shop is notified by
  email — nothing appears on the site until approved.
- Note: submission is not currently restricted to logged-in purchasers; moderation is the
  effective quality gate today.

---

## Cross-cutting expectations

**US-X.1 — Use the shop in my language**
As a visitor, I want all configurator, cart and checkout text — and the product content itself —
in my selected language, so that the whole journey reads naturally in every active shop
language.

**US-X.2 — Real-time, no-reload interaction**
As a shopper, I want selections, prices and visualization to update without full page reloads,
so that configuring feels fast and responsive.

**US-X.3 — Use the shop on any device**
As a visitor, I want the listing, configurator and checkout to work well on a phone or tablet,
so that I can buy wherever I am.