PRD: Receipt templates

Module	Commerce	PRD ID	PRD-RCP-001
Status	Ready to dev	FEAT	RCP
Epic	—	Plane	BANA-1530
Date	2026-06-15	Version	v1.0
Packages	@nx/commerce · @nx/core	URD	RCP
Surface	Client · Owner/MgrSale · POSBO · Ops
Owner	Phát Nguyễn

What a receipt template is

Every sale ends in a printed receipt, but merchants do not all want the same one. A coffee merchant wants its logo and a QR code for the loyalty program; a retail counter wants a barcode and a compact line-item table; a multilingual venue wants a Vietnamese receipt at one channel and an English one at another.

A receipt template is a named layout scoped to a merchant or a specific sale channel, and belonging to one language. It is authored in two places: the Owner/Manager designs one for their own merchant right on the Client page, and the operations team designs one on the merchant's behalf in Back Office - both share the same block vocabulary, drag-drop blocks, bind fields, and preview right on the form before saving.

The fixed block vocabulary, and one default per scope and language

A template's layout can only be assembled from a fixed block vocabulary: text, line, image, line-item table, barcode, QR code, and a grid for side-by-side rows. The layout is validated the moment it is saved against exactly this vocabulary - a block type outside the set, or a block missing a required field, is refused before it is stored, so a malformed slip never reaches a printer.

Each scope and language has exactly one default template at any time - promoting a new one automatically retires the old default, with nothing for the merchant to unset by hand.

Why a template surface is needed

Without a template surface, a merchant cannot change the header, reorder sections, add a barcode, or print in a second language without an engineering change. There is also no safe place to store these layouts: a free-form document would let a malformed receipt - a column with no field, a grid that never terminates - slip through and jam the printer at the worst moment, mid-checkout.

One template, from design to printout

A member of the operations team opens Back Office, goes to merchant management, opens the Receipt templates section for a specific merchant, and designs an 80mm receipt: a logo image, a centered merchant name, a dashed separator, a line-item table (name · qty · price), a totals grid, and a QR code bound to the order reference. They mark it the default for Vietnamese. The layout is validated and stored.

At checkout, the cashier on POS completes payment; the system picks the merchant's default Vietnamese template, binds the order's fields and items into it, and renders a 576px-wide monochrome raster the thermal printer prints. Before going live, the cashier had already pressed the Test print button in Printer settings on POS to confirm the printout matched the design.

Later the operations team adds an English template for the merchant's take-away channel and marks it default for English - the previous English default for that channel is retired automatically.

The easiest thing to get wrong

POS never designs or configures a template

The point of sale (POS) has no design or setup function for receipt templates. It only syncs the latest template whenever it is updated on the Client page or in Back Office, then uses exactly that template to print once checkout completes. No editing canvas, no setup form, no "edit template" button anywhere on POS.

Every layout change has to happen on the Client page or in Back Office, then wait for POS to sync - there is no shortcut directly on the point of sale.

1. Goals & Non-Goals

Goals

• A named receipt template scoped to either a merchant or a sale channel, in a chosen language - authored on the Client page (by the Owner/Manager, for their own merchant) or in Back Office (by the operations team, for the merchant).
• Layout assembled from a fixed block vocabulary - text, line, image, line-item table, barcode, QR code, and a grid for side-by-side rows.
• Validate the layout on every save - a template that does not conform to the block vocabulary is refused before it is stored.
• One default per scope and language - promoting a default automatically unsets the previous one for that scope and language.
• Blocks bind to live order data (fields, item rows) resolved at print time, with per-field number / currency / date formatting.
• Render a template to a monochrome raster sized for 58mm or 80mm thermal paper, sent straight to the printer the moment checkout completes on POS.
• Full lifecycle - create, edit, list/filter, status (Activated / Deactivated / Archived), soft-delete - scoped per merchant.

Non-Goals

• Pixel-level specification of the Back Office drag-drop editor - canvas layout, keyboard shortcuts, drag animation - this PRD fixes the template contract (block vocabulary, validation, default) and the rendering to a thermal printer, not the fine-grained behavior of the editing canvas.
• E-invoice / legal tax-invoice layout and issuance - the fiscal invoice is governed by Tax & Invoice, not by these print templates.
• Printer transport / driver selection (USB, Bluetooth, network) - the template produces a raster; delivering it to a device is a printing-device concern.
• Email / PDF receipts - this increment targets thermal print only.
• Cross-merchant template sharing or a global template marketplace.
• Designing or setting up templates on POS - POS only syncs the latest template from the Client page or Back Office and uses it to print and test-print, with no design or setup function of its own.

2. Success Metrics

Metric	Target / signal
Layout safety	A malformed layout (missing field, bad block type) is refused on save - zero malformed templates reach a printer
Default integrity	Each (merchant-or-channel, locale) has at most one default template at all times
Scope coverage	A template can be attached to a merchant or to a specific sale channel, in a chosen language
Render fidelity	The raster image matches the declared paper width (58mm → 384px, 80mm → 576px) with no layout distortion on print
Data binding	Order fields and line items appear on the printed slip via their declared field bindings and formats

3. Personas & Scenarios

Persona	Goal in this feature
Operations team	Design the receipt for a merchant in Back Office - branding, sections, barcode/QR - scoped to a merchant or a specific sale channel, and set the default per language
Owner/Manager	Design their own merchant's receipt right on the Client page - same block vocabulary, same layout validation as Back Office
Cashier	Print a correct, readable receipt at checkout without configuring anything on POS

Core scenario: a member of the operations team opens Back Office, goes to merchant management, opens the Receipt templates section for a specific merchant, and designs an 80mm receipt - a logo image, a centered merchant name, a dashed separator, a line-item table (name · qty · price), a totals grid, and a QR code bound to the order reference. They mark it the default for Vietnamese. The layout is validated and stored. At checkout, the cashier on POS completes payment; the system picks the merchant's default Vietnamese template, binds the order's fields and items into it, and renders a 576px-wide monochrome raster the thermal printer prints. Before going live, the cashier had already pressed the Test print button in Printer settings on POS to confirm the printout matched the design. Later the operations team adds an English template for the merchant's take-away channel and marks it default for English - the previous English default for that channel is retired automatically.

4. User Stories

#	As a	I want	So that
01	member of the operations team	to design a merchant's receipt in Back Office from a fixed set of blocks (text, image, separators, an item table, barcode, QR)	the slip reflects the merchant's brand without an engineering change
02	member of the operations team	to set one default receipt per language	checkout on POS always picks a sensible layout
03	member of the operations team	to give one of the merchant's sale channels its own receipt	a delivery slip can differ from the dine-in slip
04	member of the operations team	to bind the item table and totals to live order data	each receipt prints the real order
05	member of the operations team	a broken layout rejected when I save it in Back Office	I never discover the problem at the printer mid-sale
06	Owner/Manager	to design my own merchant's receipt right on the Client page, using the same blocks and layout validation as Back Office	I can make changes myself without asking the operations team
07	cashier	to test-print a receipt in Printer settings on POS before going live	I can confirm the printout matches the design

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	A named receipt template is scoped to either a merchant or a sale channel, in a chosen locale.	✅	URD-RCP-001 · URD-RCP-004
FR-002	Each template declares a paper width from the list the platform supports - currently 58mm and 80mm. • The list is extensible without changing the template structure. • A width outside the list is refused on save. • Each template also declares a base font size.	🔶	URD-RCP-002
FR-003	Template name is unique within a scope and language - the same name is reusable across different languages and is soft-delete aware.	✅	URD-RCP-003
FR-004	Layout is an ordered list of blocks from a fixed vocabulary: text, line, image, line-item table, barcode, QR code, grid.	✅	URD-RCP-006
FR-005	The layout is validated against the block vocabulary on create and update; a block type outside the vocabulary or a block missing a required field is refused before it is stored.	✅	URD-RCP-007
FR-006	Text, line-item, barcode, and QR blocks bind to dynamic order fields through syntax, resolved at print time - for example a text block declaring and another declaring prints the exact "Customer name" and "Total" of the order just paid.	✅	URD-RCP-008
FR-007	The line-item table renders configurable columns (field · header · width · align · format) with an optional header row.	✅	URD-RCP-009
FR-008	A grid block lays children into proportional columns with alignment / justification for side-by-side rows (up to 5).	✅	URD-RCP-010
FR-009	Blocks carry presentation styling - alignment, weight, transform, decoration, borders, colors, padding.	✅	URD-RCP-011
FR-010	Numeric, currency, and date values format per a declared format on the block or column.	✅	URD-RCP-012
FR-011	Exactly one template is the default per scope and language. Promoting a default unsets the previous one atomically.	✅	URD-RCP-005
FR-012	A template renders to a monochrome raster sized for its paper width (58mm → 384px, 80mm → 576px). • On POS, the default template is synced whenever it changes on the Client page or in Back Office. • Once checkout completes, this raster is sent straight to the thermal printer.	✅	URD-RCP-013 · URD-RCP-017
FR-013	Templates carry a lifecycle status (Activated / Deactivated / Archived) and are soft-deleted.	✅	URD-RCP-014
FR-014	All operations are confined to the user's own merchant and gated by receipt-template permissions. Templates are listable/filterable by scope, locale, status, and default flag.	✅	URD-RCP-015 · URD-RCP-016
FR-015	The Owner/Manager designs a receipt template for their own merchant right on the Client page - same block vocabulary, same layout validation as the Back Office screen.	🚧	URD-RCP-017

5.1 Acceptance Criteria

• Create a template in Back Office with a name, a scope (merchant or a specific sale channel), and a language → the template is stored, scoped exactly to what was chosen.
• On the Client page, an Owner/Manager creates a receipt template with a valid layout → the template is stored and works exactly like one created in Back Office.
• Save a template with a 58mm or 80mm paper width → accepted. Save a template with a paper width outside the supported list → refused.
• Give a new template the same name as another live template in the same scope and language → refused; reuse the name of a soft-deleted template → accepted.
• Assemble a layout from text, line, image, line-item table, barcode, QR, and grid blocks in any order → the layout is stored in exactly that order.
• Save a layout with a block type outside the fixed vocabulary, or a block missing a required field → refused, nothing is stored.
• Bind one text block to and another to , then test-print → the printed slip shows the exact "Customer name" and "Total" of the order.
• Configure a line-item table with name, quantity, and price columns plus a header row → the printed slip shows those columns in the declared order and format.
• Place 3 blocks side by side in a grid → they split into proportional columns per the declared alignment; add a 6th block to the same grid → refused.
• Give a text block bold weight, center alignment, and a border → the printed slip renders exactly those properties.
• Declare a date format on a date field → the printed slip uses that format, not the platform's default.
• Promote template B as the Vietnamese default while template A is currently the Vietnamese default for the same merchant → B becomes default, A is automatically retired; exactly one default holds at all times.
• A template is updated on the Client page or in Back Office → the next print on POS uses the latest template right away, with no action needed on POS.
• Complete a payment on POS → the system fetches the default template for the order's language and channel, binds fields and line items, renders a raster of the correct paper width, and sends it to the printer.
• Press the Test print button in Printer settings on POS → a receipt prints immediately using the current default template, with no real order needed.
• Move a template to Deactivated → it is no longer eligible to be picked as default at checkout. Delete a template → it disappears from the list but remains soft-deleted, no data lost.
• Open the template list in Back Office and filter by scope, language, status, and default flag → only matching templates appear; a user from a different merchant never sees this merchant's templates.

6. Non-Functional Requirements

Area	Requirement
Layout integrity	The layout is strictly checked against the fixed block vocabulary on save; a non-conforming layout is rejected with a clear reason, never stored
Default consistency	Setting a default and retiring the previous one for the same scope and language happen in one atomic step
Tenancy & permissions	All operations confined to the user's own merchant; gated by receipt-template create / read / update / delete permissions under commerce
Scope link	A template attaches to a merchant or a sale channel via the single link that scopes it to either one
i18n	Templates are per-locale; a merchant or channel keeps one template set per language and one default per language
Render determinism	A given template + order data renders to a deterministic monochrome raster of the correct width for the paper size
Soft-delete	Templates are never physically removed; name and default uniqueness are evaluated only over live rows

7. UX & Flows

Authoring on the Client page or in Back Office & default resolution

Print at checkout on POS

The authoring surface exists in two places: on the Client page, where the Owner/Manager designs a template for their own merchant, and in Back Office, under merchant management, where the operations team designs one on the merchant's behalf. Both places pick the scope (merchant or channel) and language, choose the paper width, drag-drop the ordered blocks, bind each block to a data field, preview the rendered slip right on the form, and mark the template default for that language. POS has no authoring surface at all - it only syncs the latest template whenever it is updated on the Client page or in Back Office. Printer settings on POS carries a Test print button - the cashier presses it to print immediately using the current default template with no real order needed, to check it before it goes into live use.

8. Data & Domain

Entity	Role
Receipt template	A named, locale-aware layout scoped to a merchant or sale channel; carries paper width, base font size, default flag, status, and the block layout
Block vocabulary	The fixed set of layout elements - text, line, image, line-item table, barcode, QR code, and a recursive grid - each with its own styling and (where relevant) data binding
Scope link	The single link that scopes a template to either a merchant or a sale channel

Conceptual only - the full block vocabulary, field bindings, and invariants live in the commerce domain model. The block layout is stored as a structured document and validated on every write.

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	Merchant & sale channel (MER, SC)	a template's scope is one of these; the scope must exist first.
02	Permissions (Permissions)	receipt-template create / read / update / delete are gated under commerce.
03	Sale / order data (Orders)	blocks bind to order fields and line items resolved at print time.
04	The shared platform	the template model, the block vocabulary, and the rendering capability.

Assumptions

#	Assumption	What breaks if it is wrong
01	The merchant or sale channel a template targets already exists.	The template cannot be created for lack of a valid scope to attach to - the merchant or sale channel must exist before a template can be created.
02	The point of sale prints a monochrome raster to a 58mm or 80mm thermal printer.	The rendered raster width does not match the physical paper, and the printout is cut off or distorted.
03	A merchant chooses a language per template; an order carries enough fields and line items to populate the bound blocks.	An order missing a field or line item that a block is bound to cannot resolve that block at print time, and the printed slip is missing exactly that piece of data.

10. Release Plan & Criteria

Aspect	Plan
Phase	P2 - RCP in the URD feature catalog
Rollout	All merchants; no feature flag
Migration	None - new concept; merchants without a template fall back to the built-in default slip
Launch criteria	Templates create / edit on the Client page or in Back Office, scoped to a merchant or channel per language; a malformed layout is refused on save; exactly one default per scope and language; POS has no design or setup function, only syncing the latest template - at checkout, the default template renders to a raster of the correct paper width and is sent to the thermal printer
Monitoring	Save-rejection rate by reason (invalid layout, unsupported paper width), default-conflict occurrences, render errors per merchant

References

• URD: Commerce - RCP
• Sibling PRDs: Organizer & merchant · Sale channels · Categories
• Module: Commerce - URD
• Developer: @nx/commerce · @nx/core

Risks & Open Questions

#	Risk / question	Mitigation / status
01	A malformed layout jams the printer mid-sale	Layout is strictly validated on every save against the block vocabulary; a non-conforming template is refused before it is stored
02	Two defaults for the same scope and language	Promoting a default atomically retires the previous default for that scope and locale
03	Wrong-width raster on the wrong printer	The template declares its paper width; rendering sizes the raster to it (58mm → 384px, 80mm → 576px)
04	A removed template's name blocks re-use	Name and default uniqueness are soft-delete aware - evaluated only over live rows
05	Pixel-level detail of the Back Office drag-drop editor is not specified here	Deliberate - this PRD fixes the template contract and the rendering; the editing canvas is a separate Back Office surface

Frequently asked questions

#	Question	Answer
01	Who can design a receipt template?	Two places: the Owner/Manager designs one for their own merchant right on the Client page, and the operations team designs one on the merchant's behalf in Back Office - same block vocabulary, same layout validation. POS has no design or setup function; it only syncs the latest template from the Client page or Back Office and uses it to print.
02	Can each sale channel have its own receipt?	Yes - a template is scoped to either a merchant or a specific sale channel, so a delivery channel can print a different slip from dine-in.
03	How does language work?	Templates are per-locale. A merchant or channel keeps a template per language and one default per language; checkout picks the default for the order's language.
04	What happens if my layout is broken?	It is refused when you save it in Back Office - the layout is validated against the fixed block vocabulary, so a missing column field or an unknown block type is caught before it can ever reach a printer.
05	Can I have two default receipts?	Not for the same scope and language - marking a template default automatically retires the previous default for that merchant-or-channel and locale.
06	What can I put on a receipt?	Text, separators (lines), an image (e.g. logo), a line-item table with configurable columns, a barcode, a QR code, and a grid for side-by-side rows - each with its own alignment, styling, and data binding.
07	How do I know the printout matches the design?	Press the Test print button in Printer settings on POS - a receipt prints immediately using the current default template, no real order needed.
08	Does this print legal tax invoices?	No - the fiscal e-invoice is governed by Tax & Invoice. These templates are for the printed sales receipt.