Shop Basics

Reference status: 2026-08-01

dbxShop is the shop application of dbxapp. It now includes the public catalogue, product search and filter, shopping cart, checkout, payment methods, orders, invoices, revocation, media, article groups, attributes, shipping groups and sales channels. Administration is in a separate module dbxShop admin.

The shop uses the normal dbxapp modules: routing over dbx run1, templates on dbxTPL, data access on dbxDB, structure about DD, forms about dbxFormlists of: dbxReport, CMS pages for legal texts and OpenWin for admin dialogues.

Technical overall picture

dbxShop covers the path from a well-kept product to a traceable order:

The shop is not an isolated external system. CMS, users, media, workflow, mail, PDF, configuration and designs are connected via the existing dbxapp modules.

Roles and typical tasks

Role	Typical tasks
Visitor/Kunde	search, filter, view product, shopping cart, checkout, view order/Rechnung, send revocation
Product care	Maintain product, group, attributes, images, price, tax, inventory and shipping
Shop admin	Manage orders, payments, invoice, shipping, tracking, legal texts and settings
Channel manager	Configure channels, check mapping, export products, monitor webhooks
Developers	Extend repository/Service/Adapter without moving price or rights checks to the template

Product life cycle

1. Create a product with a unique SKU and understandable slug.
2. Maintain title, description, product type and active status.
3. Define gross/net price, tax bracket and, if applicable, stock.
4. Assign a primary group and optional further groups.
5. complete attributes of the groups; Mark filterable attributes explicitly.
6. Assign product or group images from the central media administration.
7. Check shipping groups and delivery information.
8. internal and Activate external channels and maintain overrides.
9. Check product preview in catalogue and detailed view.
10. release of the product or Publish the appropriate workflow.

Groups are more than navigation. You can bundle presentation, attributes, control and shipping defaults, and channel groups. A specific product value wins, an empty /erbender value uses the technically intended group default.

Customer experience

Catalogue

The public catalogue combines search, group tree and attribute filter. Shown are only active, for the internal Shop-Channel released products. Product cards come from a TPL report; As a result, filters, hit numbers and pagination remain part of the report pipeline, although no classic table is visible.

Product detail

The detailed view shows:

• Media gallery and primary image,
• title, short and long description,
• price/tax information,
• delivery time, shipment and stock,
• visible product attributes,
• shopping cart action,
• Group-dependent detail and gallery template.

An SKU or ID from the URL is always checked against active channel, active status and access rules.

Shopping cart

The session shopping cart is only a user intention. Before display and checkout, products, quantities, price, tax, inventory and availability are again determined from the repository. Sums or prices passed by the browser are never the basis for calculation.

Checkout

The checkout uses dbxForm and guides the customer through contact/address data, payment method, notices and consents. Only configured payment methods are offered. Legal texts can be saved as a snapshot in the order so that the status accepted at the time of purchase is maintained.

Language-dependent surface

Catalogue filters, purchase and shopping cart form, checkout and the public order list have their own German, English and Spanish FDs:

In addition to field labels, the respective FD also provides page/bar titles, report columns, status labels, empty states, payment and validation instructions and confirmation texts. dbxForm and dbxReport load these messages via their common FD mechanism. General browser buttons such as Ja/Nein come from the central JavaScript translation.

Product names, group names, attributes, delivery texts or payment instructions from the database are stored domain data. In a monolingual shop table they are not translated by a FD. This would require real language tables and suitable language DDs.

Order Life Cycle

An order has two technically separate states:

• Order/settlement status, e.g. B. Payment pending, in processing, shipped or completed.
• Payment status and provider reference, e.g. B. open, confirmed, failed or refunded.

shop order item saves the purchase time-related snapshot. Changes to SKU, title, price or tax of a product must not subsequently change existing order positions. Status changes will be made in shop order history understandably recorded.

Price, tax, shipping and stock

• Currency and gross/net display come from the shop configuration.
• Control classes are configured centrally and a product or assigned to the default.
• Channel prices can override the internal price; The defined inheritance value again uses the product/group price.
• Shipping groups determine delivery time, costs and exemption limits.
• If the stock is active, availability and quantities are checked on the server side.
• Digital products can use their own delivery/shipping route.

Rounding and summation are part of the technical logic. Templates only format already calculated values.

Module allocation

dbxShop is deliberately frontend and uses the active frontend design. dbxShop admin It has the suffix. admin and is available for administrators from the design router default design admin dissolved. Currently, the admin design dbxapp.

Front-end routes

Call pattern:

dbx run1	Task
Start, catalog	Catalog with search, group and attribute filters
Product, Details	Product detail based on SKU/Parameter
cart	Show shopping cart and process quantities
Checkout	Collect customer data, payment method and consent
paypal start	Start PayPal Expiration from Checkout
paypal return	Record PayPal returns and book payment
paypal cancel	Treat cancelled PayPal payment
amazon pay return	Processing Amazon Pay Return
amazon pay cancel	Dealing with Cancelled Amazon Pay Payment
Order, Orders	own or Show recent orders
invoice pdf	Provide an accessible invoice as PDF
channel webhook	Accept external order/channel feedback
Legal, Terms	Publish CMS legal texts of the shop
Return, Returns, Withdrawal	Issue withdrawal page and form

Example of a CMS or template inclusion:

Admin routes

Call pattern:

dbx run1	Task
dashboard, Start	Key figures and quick accesses
Installer	Ensure DD scheme, defaults and test basis
Products	List of articles, selection and mass actions
product edit	Editing articles or re-creating them
product tree move	Move article group in the tree
product channel mapping	Maintain channel-specific article data
products help	Contextual product assistance
Groups	Managing hierarchical article groups
attributes	Manage attribute definitions
product attributes	Maintaining Attribute Values of an Item
Shipping groups	Manage shipping types and costs
channel groups	Creating sales scenarios from channels
Channels	Configure internal and external sales channels
Media	Show and upload shop media
assign media	Assign media articles or groups
Orders	Order report with filters and actions
order detail	Maintain status, payment, shipping, tracking and note
order invoice	Show invoice as HTML
order invoice pdf	Generate or open invoice PDF
Legal	Maintaining legal texts in the CMS
Returns	Administration of revocations
Settings	Shop, tax, payment, mail and shipping settings
payment test	Check configured payment providers

Module access is via dbxShop admin/cfg/config.php to the group admin restricted. Domain actions must not circumvent this module authorization by direct, unprotected auxiliary routes.

Data model

All shop DDs currently use the server dbxShop|dbxShop.db3. Each table has the primary ID id. The physical tables are synchronized from the DD files and should not be maintained in parallel as a handwritten SQL schema.

Article and presentation

DD	Table	Purpose
shopProduct	shop product	SKU, Slug, Title, Type, Price, Tax, Shipping, Stock, Active Status
shopProductGroup	shop product group	hierarchical groups, control/shipping defaults, map, detail and gallery templates
shopProductGroupMap	shop product group map	Article-to-group, including primary group
shopProductImage	shop product image	CMS medium or image path for article /Gruppe
ShopAttributeDefinition	shop attribute definition	Group-related text, selection or number attributes
shopProductAttributeValue	shop product attribute value	Specific attribute values of an item

The article group can inherit presentation specifications, for example card template, detail template, gallery template, image number, image mode, overflow and click behavior. Technical article values remain in the article; the group provides defaults and categorisation.

Shipping and Channels

DD	Table	Purpose
shopShippingGroup	shop shipping group	Route, delivery time, cost and exemption
shopProductShippingGroupMap	shop product shipping group map	Item-to-ship group
shopchannel	shop channel	Platform, connection, access, Export/Import and test status
shopProductChannel	shop product channel	Activation, Channel SCU, Price/Shipment Ride and Export Status
shopChannelGroup	shop channel group	reusable group of sales channels
ShopChannelGroupChannel	shop channel group channel	Channels within a channel group
shopProductChannelGroupMap	shop product channel group map	Article-to-channel group

Direct channel assignments and inherited assignments via channel groups are resolved together. A channel-specific price of -1 Similarly, the article, i.e. group value is used.

Order and revocation

DD	Table	Purpose
shopOrder	shop order	Customer, sum, channel, payment, invoice, inventory, shipping and legal snapshots
shopOrderItem	shop order item	Immutable Order Position Snapshot
ShopOrderHistory	shop order history	Status and technical events of an order
shopWithdrawal	shop withdrawal	Revocation with regard to order/Kunde and admin status

Order items store SKU, title, quantity, price, tax and shipping at the time of order. Subsequent article changes must therefore not retroactively rewrite an existing order.

Installation, DD sync and test data

dbxShopRepository::install() Synchronizes the 17 shop DDs, creates standard channels and corrects certain assignments. Synchronization is performed with schema sync version limited. A change to a DD therefore also requires a new schema version identifier if the automatic synchronization is to run again.

If items, shipping groups, channel groups or pictures are missing, the current shop calls seedDemoProducts() on. The development project may contain test data. The included test data includes software and service groups, shipping groups, channel groups and demo items.

Tools for targeted test data and mockups are available at:

Catalogue and product presentation

The catalog shows only active articles that are sent to the internal channel Shop assigned to them. It shall support:

• full text search with weighted article, group and attribute values,
• hierarchical article groups and breadcrumbs,
• filterable attributes,
• group-specific map and detail templates,
• article and group images from the CMS media stock,
• Tax, supply and inventory information.

Existing templates include:

New variants are supplemented as shop templates and selected via the group. The service validates the template name; Unchecked file paths from database values are not allowed.

Uniform loading of product lists

Product lists always use the same simple process in the repository:

1. Product lines or Load light filter candidates.
2. Relations for the required quantity of products over dbxDB Load the existing DDs.
3. Assign groups, shipping, channels, images and attributes in memory via ID.
4. Represent only the visible catalogue page completely.

products() for administration and productsByIds() Use both for the public report decorateProducts(). The method forms a short-lived data view only for the current call. It is not a process- or request-wide cache and therefore does not require disability. individual searches such as: productById() and productBySku() remain unchanged compatible.

dbxDB::select1() has a universal request local single set cache. It does not repeat identical DD/WHERE/column accesses and is discarded for each write access to the same DD. Transactions bypass this cache. The repository quantity queries shall remain unaffected: They are still the way to go for full product lists with many different IDs, while the central cache avoids repeated access to the same single set.

The representation also follows the quantity principle. The service reads once per request the existing in a map or detail template {replacement name It only generates their values. As a result, a catalogue card no longer builds an invisible detail gallery, attribute table, shipping/stock view or dbxForm instance. Own shop templates remain compatible: Once they use a known placeholder, its value continues to be fully generated. The cache contains only the placeholder names of the local template file, not product, user or form data.

The admin image list follows the same contract. allImages() loads all required product and group titles in a maximum of two volume queries and assigns them via ID. New admin lists must not be included within a result loop select1() Call for pure names. The central cache is not a substitute for a technically related list data view.

Shopping cart and checkout

The shopping cart is displayed in the PHP session under dbxShop cart guided. The checkout collects name, email, telephone, delivery address, note and payment method. Legal texts and revocation policy must be confirmed.

Changing cart actions remain POST actions in the existing dbxReport-/dbxForm-Contract. remove and Clear are named Submit buttons; ajax.js Takes over their name/value in addition to the form data. After a confirmation dialog, a short-lived hidden field holds the confirmed name/value-Value fixed and the regular form submit continues to decide between AJAX and browser navigation. This allows removal and emptying to work with both AJAX and native form fallback. The existing dbxForm-CSRF test remains unchanged; a separate dbx token was not introduced for this.

The current total counter is at the returned shopping cart root in data-dbx-shop-cart-count. The module related design/js/shop.js synchronized with it ajax:after All menu badges. The dbxapp asset version VERSION ensures that browsers reload the corrected kernel libraries.

The sequence is:

1. Check cart positions against current products.
2. Check stock if: stock enabled is active.
3. Validate customer data and payment method.
4. Save legal texts and revocation as snapshot when activated.
5. Create orders and positions.
6. Reserve stock if necessary.
7. For offline payment issue confirmation page and mail.
8. With PayPal/Amazon Pay switch to the provider and process returns.
9. Log order and payment events in the history.

Guest orders are placed with checkout guest allowed controlled. The public display of an order or invoice must continue to use the access verification implemented in the Service; A freely transferred ID alone is not an authorization.

Types of payment

Currently, the configuration supports:

Type of payment	Activation
Advance /Überweisung	Switches plus optional banking data and instruction
Invoice	Switch plus billing note
PayPal	Switch, mode, client ID and client secret
Amazon Pay	Switch, mode, region, merchant/store/key data and private key

PayPal and Amazon Pay are only offered in the checkout when the required access data is available. New providers belong in their own adapter class; Secrets must not be written in templates, logs or test editions.

Legal texts, CMS and revocation

The shop ensures the required CMS pages under a shop folder. Legal texts and cancellation content are maintained in the CMS, not duplicated permanently as HTML in the shop template. During checkout, snapshots can be stored in the order so that the version accepted at the time of purchase remains traceable.

Cancellations are made via the frontend form in shop withdrawal stored and processed in the admin module. Customer and admin mail can be activated separately.

Media

Product images preferably reference central CMS media via media id. One image path remains possible as a fallback for existing or generated files. An image can be assigned to an article or article group. Group images serve as fallback and visual navigation in the catalogue.

The configurable CMS slot is standard Shop. Media must not be treated as trustworthy by file names alone; Upload destination, file name and file type are limited on the server side.

Channels and external platforms

Standard channels are:

dbxShopChannelConnector encapsulates connection testing, payload normalization and article export. Platform-related implementations exist for eBay, Amazon, mobile.de and classified ads; In addition, there is a generic middleware way. The internal channel Shop No external export is required.

A visible channel configuration does not automatically mean that there is a production contract or all API permissions. Before live operation, access data, API scopes, marketplace/seller context, policies, webhook authentication and error repetition must be checked.

The Webhook endpoint is:

Webhook secrets and provider signatures are security limits. A new import route may not generate orders unchecked from any JSON.

Settlements

The admin page Settings manages, inter alia:

• Active status, standard channel and currency,
• gross/net display and three tax brackets,
• B2B, warehouse and channel switches,
• Guest order and legal text snapshots,
• customer/admin mail and sender,
• Prepayment, invoice, PayPal and Amazon Pay,
• digital delivery and flat-rate shipping,
• The CMS media slot.

Configuration is performed with dbx()->get cfg('dbxShop') read and stored via the central configuration interface. Do not introduce a second JSON or ENV configuration for the same values.

Real code paths

Repository instead of DB access from the template

The second parameter of productBySku() requires an active product. The service class additionally checks channel and presentation context. A template only receives the finished values and does not generate a shop query.

Export product to a channel

exportProductToChannel() loads channel, product, mapping and connector status through the repository. An admin controller should not itself assemble a provider payload from request fields.

Order report

The admin view passes this data to dbxReport. Repository and report have different tasks: The repository knows the shop query, dbxReport knows filter status, pagination, formatting and actions.

Payment adapters

Provider adapters encapsulate authentication, Request/Response and test mode. The service remains responsible for local order status, idempotence, return and history.

Extension scenarios

New product attribute

If editors need an additional feature such as material or contract term, usually no new column in shop product used. An attribute definition can be assigned to a group, marked as filterable and filled per product.

New payment method

1. Complement configuration fields and secure secret treatment.
2. own adapter with isConfigured, Start/Erstellung, Return/Bestätigung and implement connection test.
3. Offer payment method only with full configuration in the checkout.
4. local order before or unambiguously reference the provider request.
5. process repeated returns/Webhooks idempotent.
6. Write history and error message without secrets.

New sales channel

1. Define channel type and configuration.
2. dbxShopChannelConnector or complement a platform-specific adapter.
3. Make product mapping and necessary policies/IDs maintainable.
4. Provide test compound without production mutation.
5. Store export status, external IDs and provider response.
6. Authenticate and normalize webhook.
7. technically specify error repetition and partial errors.

New representation variant

A new map or detail view is created as a shop template and optional CSS within the shop design. The group chooses the permitted template name. Product data, prices and rights remain unchanged in Service/Repository.

Operation and troubleshooting

• Check dashboard numbers first against repository queries and active filters.
• Missing products: Check active status, internal channel, group and rights.
• Wrong price: Check product value, group/channel loverride, tax indicator and currency separately.
• Checkout errors: Check form validation, inventory, consent and provider configuration.
• Double order: Check provider reference, return potency and webhook history.
• Missing picture: shopProductImage, media id, check active dbxMedia file and group fallback.
• Export error: Test channel testing, mapping, external policies/Scopes and stored connector response; Never copy secrets into the UI.

Enlargement rules

• New tables first as DD in dbxShop/dd Modeling.
• Every shop table needs id as primary key with autoincrement semantics of the respective database.
• Data access belongs in dbxShopRepositoryNot in templates.
• The front end is in dbxShopService.
• Admins belong in dbxShopAdmin and remains admin-protected.
• Use new inputs dbxForm and FD, new lists dbxReport.
• Price, tax, shipping and order values are calculated on the server side.
• IDs from request or session are always checked against rights and record reference.
• Secrets are not output or logged in system messages.
• External calls receive timeout, error handling and traceable status; You must not leave local orders inconsistent.

Checklist

• DD-Sync runs through an empty development database.
• Each table shall have: id and a working Autoincrement-ID.
• Demo articles appear in the catalogue and can be filtered.
• Cart adds, changes and removes positions correctly.
• Confirmed single deletion and emptying work with AJAX; The menu badge immediately shows the current total.
• Checkout rejects incomplete data and lack of consent.
• Offline payment generates order and positions exactly once.
• Provider return is repeatable or does not create a double order.
• Own orders and invoices are accessible, strangers are not.
• Admin reports, forms and mass actions work.
• Legal texts, revocation, media and mail counters have been checked.
• Channel tests and exports show errors without spending secrets.
• dbxapp and Flowers Make the shop readable and responsive.

Related documentation

• Security, integrity and performance
• Shop AI reference
• dbxDB, dbxDD and FD
• dbxForm
• dbxReport
• Design, themes and skins
• Mandatory rules for AI agents