Generated from plan.md by build-plan-html.py. Edit the Markdown, then re-run the script.

Sales Return (Back-Office) — plan

0. Summary

What the user gets. A Back-Office user can take goods back against a completed sales invoice and pay the customer back. A return starts in one of two ways (owner, 5 Oct 2026, Revision 4): New Sales Return on the Sales Returns list opens the form with a list of completed sales invoices and a search — the user picks one; or Return Items on a Completed invoice (row menu or view page) opens the form with that invoice already chosen. Either way the return is always against one invoice. The user picks what comes back and how many (never more than was sold minus what is already returned), picks the serial numbers from the ones that were sold, says for each line what happens to the item (Back to stock or Write off — pre-filled from the item's value when it has one, else the store setting), chooses the reason and the refund method, and sends it for approval. The refund for a line is the invoice line's own stored amounts, in proportion to the qty returned — so discounts, the cart share and tax come back exactly as charged, on tax-inclusive and tax-exclusive invoices alike (§3.2). An invoice older than the return limit (LIMIT_SALES_RETURN_IN_DAYS, 30 days by default) cannot be returned, except by the owner. An item marked non-refundable cannot be returned.

How it moves. Draft › Approval pending › Approved (or Rejected with a reason, back to editable) › Completed by "Complete Refund". The refund method and its reference are saved with the Draft (as the return's payment row), but only Complete Refund pays the money out, dates the credit invoice that day, puts the Back to stock lines back in stock (Write off lines stay out) and marks the original invoice Returned. Before that, nothing counts: no stock move, no money, not in the reports (the payment row is hidden with its document), not on the till. A Draft or Rejected return nobody wants is deleted. An approved return that should not happen is voided with a reason. Every status change goes through change_status() and shows in the Audit timeline.

Print and e-mail. The same as the sales invoice. Print prints the credit invoice at once with the company's saved choices. Print with options opens a full page: a checklist of what goes on the paper, a live A4 preview, copies (1–5, ORIGINAL / COPY stamp), a one-line remark, and "Save as the company default". Send Email sends the credit invoice PDF to the customer's e-mail at once; the PDF uses the same choices as the print. Print and e-mail are offered on a Completed or Voided return only — the invoice's rule.

No return without an invoice. A customer with no receipt is served at the till (exchange_return_without_receipt, role access POPC_NEW_SALES_RETURN). The Back-Office API refuses a return with no original invoice.

What exists today and what changes. The Back-Office already has a one-click return (POST /api/sales-returns) that writes a Completed credit invoice at once. It works from an invoice only and has seven defects (§2.5). This plan replaces its money maths (D7), fixes the other defects, and puts the approval steps in front of it.

1. Scope

1.1 In

1.2 Out (this round)

• A return without an invoice (owner, 5 Oct 2026). Served at the till only. The Back-Office API refuses original_sales_id = null (V10). The Sales Returns list still shows till returns that have no invoice — the Original Invoice cell reads "—".
• Exchange (return plus a new sale in one go). The API route exists but is a stub: sales_commit_service.create_exchange raises ServerError, so it answers 500. Not touched.
• E-invoice for a return. Today nothing sends a credit note to LHDN — einvoice_query.py:114 reads doc_type = 'SALES_INV' only. LHDN needs the original e-invoice number (UUID) on a credit or refund note. Left for a separate plan (§9A R6). So the credit invoice's print options have no LHDN QR row.
• Returning an invoice raised at the till. v1 returns Back-Office invoices only (§9A R3).
• The till using the item default. The till keeps its own store / company setting RETURNED_ACTION_CONTROL (Restock · Write off · Ask the cashier) this round; reading the new item default at the till needs the item sync and the till's item table (§9A R10).
• The item field "When a customer returns this item" (owner, 5 Oct 2026): its column, the Item › Settings row and the item import belong to the Item module. This plan only reads it and handles it being empty (§3.5).
• A damaged-goods stock location. Write off means the item does not come back into stock at all; putting it into a separate "Defective" location is not offered (§3.5).
• Store credit as a new refund type. Refund methods are the store's existing payment methods.
• Coupons (owner, 5 Oct 2026). A coupon used on the invoice stays used after a return, part or full. Nothing in coupon_master or ft_sales_promo_disc is touched.
• Notifications. None. Nobody is told by e-mail or bell that a return waits for approval; the approver finds pending returns with the list's Status filter (Approval pending, §6.2).
• The invoice view page's greyed Submit for Approval on an unpaid invoice — raised in the review, but it belongs to the invoice module. Flagged for ../invoice-bo/plan.md; not changed here.

2. Data model

2.0 Database review — every table and column a return touches (checked 5 Oct 2026)

Read from db-postgresql/tenants.schema/ on main (T = tables_pg.sql, F = functions_pg.sql, V = views_pg.sql). Checked again 5 Oct 2026 (Revision 4): about 55 table, column and line cites were right; two were wrong and are fixed in the table; the tables and columns the first pass missed are in "Also touched" below. Backend cites to sales_commit_service.py, sales_commit_repository.py, sales_document_repository.py and sales_lifecycle_service.py are on the branch Redy-20260828-BONewSales, not on main — their line numbers are checked again when that branch is merged (B0).

How the stock function treats each return line (F:4510-4541): on a CREDIT_INV at COMPLETED it loops every line and restocks only when item_entity_type = 'ITEM' AND (action_for_returned_item = 'RESTOCK' OR action_for_returned_item IS NULL) (F:4533), and not for a service / non-stock item (F:4537-4541). A WRITE_OFF line is skipped — no stock row, nothing comes back. So the choice needs no function change. (The Back-Office already writes item_entity_type = 'ITEM', ITEM_ENTITY_TYPE_ITEM in core/constants.py:574.)

Also touched — found in the Revision 4 check:

Two existing gaps found, outside this plan:

• On a void of a completed till return the reverse branch (F:4907) undoes only = 'RESTOCK', not NULL — a till line with no action is restocked on completion but not taken out again on void. Not reachable from the Back-Office (a Back-Office return is voided only at Approved, before any stock moved, and always carries an action). Reported for the till / DB owner.
• The field-option labels are capitals with notes: "WRITE OFF (ESPECIALLY FOR FNB)", "RESTOCK (ADDED BACK TO INVENTORY)" (core/field_options.py:537-541). This plan relabels them Write off and Back to stock in both field-option files (§3.5).

2.1 The return document (no new table, no new column)

A return is one ft_sales_header row, as the till and today's Back-Office write it:

Lines: one ft_sales_detail per returned line (one per batch when a line comes from two batches, the G22 rule of the invoice plan). ref_sales_detail_id points at the invoice line (always set), is_returned = true, qty returned (negative), the serials / batch picked (§2.5 D2), action_for_returned_item = RESTOCK or WRITE_OFF — always set by the Back-Office, never NULL (§3.5). Every other item field is copied from the invoice line (§2.5 D6): item_barcode, item_category_code, uom_code, item_cost, is_service_or_non_stock, is_serialized, is_batch_tracked, is_taxable, tax_class_id.

Link: one ft_sales_parent_child row (parent = invoice, child = return), written on create, removed when the return is deleted.

Refund money (owner, 5 Oct 2026, decision A). The refund method and its reference are kept on the Draft by writing the return's ft_sales_payment row when the return is saved: negative local_amt = the refund total, the chosen tender (tender_type_id, tender_name, tender_code, tender_category), payment_ref_no = the Reference no. typed on step 2, currency_iso_code from the invoice — through the existing sales_commit_repository.insert_sales_payment (:429, which already takes payment_ref_no). On every edit the row is deleted and written again with the new method, reference and total. It counts nowhere until Completed, because the §2.3 rule hides the whole document while it is Draft / Approval pending / Approved / Rejected / Voided — every reader of ft_sales_payment that adds money up must join the header and apply that rule (list in §2.3). At Complete Refund the row is re-checked, not created: exactly one live row, its amount equals the refund total recomputed under lock, its tender still passes V9; any mismatch → 409 REFUND_CHANGED and nothing is written; the screen explains it and offers the way out (V13a).

The credit invoice date (owner, 5 Oct 2026, decision D). The credit invoice is dated the day Complete Refund is pressed. In the V13 transaction, before the stock movement, the return header's doc_trx_date is set to now — doc_trx_date is the partition key (T:3007), so the UPDATE moves the row to that day's partition; no FK points at the header (T:8132-8244), so nothing breaks — together with the payment row's trx_date (its partition key, T:3264). doc_ref_no keeps the number given at Draft. The return's lines are partitioned by created_date and every reader finds them by a window on the header date (created_date >= doc_trx_date::date − 1 day, e.g. sales_commit_repository.get_returnable_lines:601-602, sales_document_repository.delete_document_rows:195); a Draft completed days later would fall outside that window. So in the same step the return's lines get the same new date: UPDATE ft_sales_detail SET created_date = <the new doc_trx_date> WHERE sales_id = <return> — PostgreSQL moves each row to the right partition and keeps its sales_detail_id, so nothing that points at a line (tax rows, stock rows written later) breaks. No delete and re-insert. The return's ft_sales_item_tax rows (partitioned by created_date, T:~3109-3142; written for returns, sales_commit_repository.py:411) get the same created_date update in the same step (a Back-Office return writes no ft_sales_promo_disc row — coupons stay used, §1.2; corrected in Revision 4) — delete_document_rows (sales_document_repository.py:196), the view page and print find them by a window on the header date. Test: a Draft completed 3 days later still shows its tax rows on the view page and print. Reporting: a completed return is reported on the Complete Refund day — sales summary, day totals and month cut-off all follow doc_trx_date (intended, decision D). Until Complete Refund the Draft's date is shown only as "Created".

Reasons (all stored as codes, shown as words). One reason per return line: units of one invoice line that came back for two different reasons are two returns, or the user picks the main reason — the till's split-by-reason is not copied (owner, 5 Oct 2026, R12 closed):

> R7 closed (owner, 6 Oct 2026): a void writes the void into the header's voided_or_returned_* columns as void_document does today; the return reason stays on each line (ft_sales_detail.voided_or_returned_reason_code — no void touches the lines). Both are kept, no new column.

2.2 Status words and colours

The invoice plan's §6.3a table applies. A return uses: Draft (neutral) · Approval pending (waiting) · Approved (accepted) · Rejected (problem) · Completed (done) · Voided (problem). The invoice gains nothing new — it already has Returned (blue, accepted). There is no Return Type tag: every Back-Office return comes from an invoice.

2.3 What counts as a sale

A return that is not Completed must not count anywhere. Today the rule bo_not_a_sale_predicate() (core/sales_doc_semantics.py:95) hides Back-Office rows at Draft / Approval pending / Rejected / Voided, and a SALES_INV at Approved. It must also hide a CREDIT_INV at Approved:

NOT (source_type = 'BO' AND (status IN ('DRAFT','FOR_APPROVAL','REJECTED','VOIDED')
     OR (status = 'APPROVED' AND doc_type IN ('SALES_INV','CREDIT_INV'))))

Same change in v2-sellable-api sales_query.bo_not_a_sale_sql() (sales_query.py:53; till sync, sales reports, e-invoice lookup). Sales reports already take CREDIT_INV as the negative side (SALES_REPORT_DOC_TYPES, sales_doc_semantics.py:40).

Payment readers (decision A). A return Draft now holds a negative ft_sales_payment row, so every reader that adds up payment rows must join ft_sales_header (on sales_id, with company_id — the payment table has none) and apply bo_not_a_sale_predicate() / bo_not_a_sale_sql(). Found by git grep "FROM|JOIN ft_sales_payment" on b01e305cd:

2.4 What the till does (checked 25 Sep 2026)

• Return with a receipt: SaleUtils().refundProcess(...) in v2-pos-client/client/lib/app/utils/module/ext/sale/sale_return_exchange_utils.dart:275. It writes CREDIT_INV / REFUND, status COMPLETED.
• Without a receipt (till only — not in the Back-Office): exchange_return_without_receipt_controller.dart:927–928 calls it with parentSaleDetails: [] — no parent link. Guarded by role access POPC_NEW_SALES_RETURN.
• With a receipt: the original header turns RETURNED on any return, part or full (sale_return_exchange_utils.dart:738); each original line gets qty_returned and is_returned = 1 when nothing is left.

The Back-Office follows the same shape so a return reads the same in every report, whichever app wrote it.

2.5 Today's Back-Office return — defects this plan fixes

Today: POST /api/sales-returns (api/sales_returns.py:161, permission sales.return.manage) → sales_commit_service.create_return (:1603). One transaction: header at COMPLETED, lines, bump_qty_returned, negative payment, parent link, stock movement. Screen: pages/sales/SalesReturnCreatePage.tsx (one page, route /sales/new-return?original=).

Kept as is: the idempotency key, the self-refund guard (S9, sales_commit_service.py:1662 — you may not refund a sale you rang up yourself), the one-transaction rule. Replaced: the refund maths (D7). Widened: the tender check — today only "tender exists and is active for the company" (get_tender_type, sales_commit_repository.py:482); V9 adds the store and stored-value rules.

2.6 Validation and safety net

The invoice plan's rule stands: the screen guides, the server decides. Every check runs on the API even when the screen greys the button.

3. Business rules

3.1 Lifecycle

Today VALID_TRANSITIONS (sales_lifecycle_service.py:51) is one flat map keyed by status, shared by the order and the invoice, and APPROVED goes only to VOIDED. Adding APPROVED → COMPLETED to that map would also open it for orders and invoices. So the map becomes per document type (VALID_TRANSITIONS[doc_type][status]), with CREDIT_INV = the invoice's moves plus APPROVED → COMPLETED; _NOUN gains CREDIT_INV: "return"; the paid-in-full gate (_NOT_PAID_REASON) does not apply to a return — its money moves at Complete Refund. The original invoice gets one new move: COMPLETED → RETURNED (and RETURNED → RETURNED writes nothing — change_status() skips a same-status call).

Why money moves at Complete Refund and not on the Draft (the invoice takes payments on the Draft): on an invoice the money comes in, so taking it early is safe. On a return the money goes out, so the Back-Office pays nothing itself until Complete Refund. Exception, owner, 6 Oct 2026 (C1): a card refund is done on the card terminal by the cashier before the Draft is saved, and its reference is keyed in — so for a card the money may already be out when the manager approves; Reject / Void / Delete then warn about it (§9A C1). The Draft records how the money goes back (its payment row, decision A) so the approver sees the method and reference; that row counts nowhere until Completed (§2.3).

Delete reuses the invoice's sales_lifecycle_service.delete_document (:332, invoice route api/sales_invoices.py:419) with doc_type = 'CREDIT_INV'; delete_document_rows (sales_document_repository.py:177) gains the ft_sales_parent_child delete (child_sales_id = $1). An abandoned Draft otherwise holds its qty against V4 for ever.

3.2 The numbers

• Lines offered: every line of the invoice with Can return > 0 (V4). A line already fully returned shows greyed with "Returned".
• Refund for a line (D7) = what the customer paid for that line, from the invoice line's stored amounts, pro-rata × qty returned / qty sold. Which stored column holds "what was paid" depends on the invoice's own flag ft_sales_header.is_tax_included_in_price (T:2994 — the invoice's flag, not today's company setting):
• tax-exclusive invoice: paid = total_amt_after_tax; tax = total_tax_amt; net = total_amt_b4tax.
• tax-inclusive invoice: paid = total_amt_b4tax (price less discounts, tax already inside); tax = total_tax_amt (shown, not added); net = paid − tax. Never total_amt_after_tax: the Back-Office stores it as unit_net × qty + unit_tax × qty whatever the flag (sales_batch_split_service.py:108-117), so on an inclusive invoice it holds the tax twice — an invoice-side storage fault, reported for the invoice plan (§9A note). Discounts and the cart share (already per unit, sales_calculation_service.py:584) are inside the stored figures, so nothing is recomputed from unit prices. Each figure is rounded half-even to the cent. The last return that empties a line takes what is left exactly: stored amount − what earlier returns of that line took — no cent drift. Same shape as the till (stored amounts pro-rata, last return takes the rest — sale_return_exchange_utils.dart:429-468), not identical: the till takes the per-unit tax from itemCartProrataTaxAmt and rounds per unit; the Back-Office pro-rates the line totals and rounds once per line. Unit Refund on screen = line refund ÷ qty, display only. The old formula item_actual_price − item_disc_amt − item_cart_prorata_disc_amt, grand = subtotal + tax (sales_commit_service.py:1723-1734) is removed.
• Never more than the items picked (owner, 6 Oct 2026). The refund total is never more than the total of the returned items' refunds: a Cash refund that would round up rounds down instead (RM 35.33 → RM 35.30, not 35.35), and the last return of an invoice pays back what is left of the payment only when that is not more than the items' value. Nor is it ever more than is left of what was paid on the invoice — then the return is refused, 409 REFUND_OVER_PAID.
• Rounding. Today a return writes rounding_amt = 0 (sales_commit_service.py:1764). New rule: the last return that empties the invoice refunds exactly what was paid on it (its live payment rows, net of change) less earlier refunds — the difference from the sum of lines goes into rounding_amt. Otherwise, for a Cash refund only (tender_category = 'CASH', core/constants.py:408), the refund total is rounded with the company rule _rounding_of(company) (sales_commit_service.py:322, snap_to_interval) and the difference goes into rounding_amt; any other method refunds to the cent.
• The refund method is never pre-selected (owner, 5 Oct 2026): the field starts empty with "Choose how to pay back", and the user picks it within V9 (one method per return for the whole refund; only the store's methods flagged for refund are listed; no cap per method — owner, 6 Oct 2026). The hint under the field reads "Only payment methods set up for refunds at this store are listed. The invoice was paid with Cash RM 120.00." Next with no method marks the field red with "Choose how the refund is paid back.", an error toast and focus (V9). Editing a saved Draft keeps the method it was saved with.
• Serials: the user ticks from the serials on that invoice line that are not already returned.

3.3 (Removed in Revision 2)

Revision 1 had the numbers for a return without an invoice here. That path is out (§1.2).

3.4 Print and e-mail — the same as the sales invoice

Everything in invoice plan §3.10 (print and e-mail as built), §3.11 (print options) and §3.11c (Last page group, page footer, one font in three sizes) applies to the credit invoice. This section names only what is different for a return. A Completed return is printed and e-mailed exactly the way a Completed invoice is.

3.4a The three ways out, and when

Which statuses: only Completed and Voided (the invoice's canPrintOrEmail rule; a return never becomes Returned). A Draft, Approval pending, Approved or Rejected return offers none of the three. A voided return prints with its VOIDED stamp.

The e-mail (services/sales_return_service.send_return_email, sales_return_service.py:334, moved to the invoice's builder services/sales_document_email.py): subject Credit Invoice {ref} — {company}, then — RM{amount} refunded once the refund is paid (always, on a Completed return); the text "We have refunded RM… for the items you returned on {date}. Your credit invoice is attached."; the amount card reads Refunded RM… (never "Amount due"); the original invoice number under it. The attachment is credit_invoice_{doc_ref_no}.pdf. Outcome written to the header as today (is_emailed, email_status, email_error_msg).

A Voided return (printed or e-mailed): the sheet title reads VOIDED CREDIT INVOICE with the VOIDED stamp, a red band under the identity panel "Voided on {date} by {name}. Reason: “…”. No refund was paid on this credit invoice. It keeps its number and date so the record stays traceable.", and no refund block (the payments choice prints nothing). The e-mail subject is Credit Invoice {ref} voided — {company} (no amount); the text "Please be informed that credit invoice {ref} has been voided. No refund was paid on it and nothing further is owed. A voided copy is attached as a PDF for your records."; no amount card. A return is voided only at Approved, so no money ever moved.

3.4b Print options for the credit invoice

The invoice's page (SalesPrintOptionsPage, kind = "return"), the same rules: the checklist beside a sticky A4 preview, re-fetched 300 ms after the last tick; Print credit invoice (primary), Download PDF, Send e-mail with the same choices; ‹ Back returns to the view page; copies 1–5 and the ORIGINAL / COPY stamp; remark (max 120 characters, print-time only); "Save as the company default (all stores)" only with ADMINISTRATION_COMPANY_MANAGE, everyone else reads "Only an admin with the Company Settings permission can change this." Two layers, as the invoice: this print › company setting › shipped defaults. Nothing is stored per user.

Document type key: CREDIT_INVOICE ↔ doc_type CREDIT_INV (one more entry in DOC_PRINT_OPTIONS and in the report service's type map). Today the renderer ignores print_options for every type other than SALES_ORDER / SALES_INV (invoice plan §3.11, "Report service"); this plan adds CREDIT_INV. Till returns (source_type not BO) print through the same renderer — they pick up the company setting too, the same as the e-invoice mail does for invoices (§9A R8).

What can be turned off — default in brackets. Counter on the page opens at "7 of 12 included".

Required on a credit invoice (not in the checklist, not counted, forced on by forceRequired(opts, "CREDIT_INVOICE") on the page and by the renderer): Company address & phone (company_address), Unit refund (unit_price), Subtotal and tax lines (totals_breakdown) — a credit invoice corrects a tax invoice, so it shows what the invoice had to show (§9A R9).

Not offered on a credit invoice: Deliver-to (deliver_to) — nothing is delivered; Discount (discount) — the unit refund already has the discount taken off; LHDN e-Invoice QR (einvoice_qr) — out of scope (§1.2); Bank details (bank_details) — the money goes to the customer, not to the company.

Always printed (fixed): credit invoice number, date, seller name, customer name, original invoice number and date, refund total. Title on the sheet: CREDIT INVOICE. The page footer (rule + "Page N of M") prints on every page; the Last page block prints once at the foot of the last page (§3.11c). One font, three sizes (§3.11c).

Storage: company_settings_json.DOC_PRINT_OPTIONS.CREDIT_INVOICE, written by the existing PATCH /api/company-settings/print-options (its doc_type list gains CREDIT_INVOICE). Missing key = the defaults above, no migration. Added to company_settings_default.json (new-company seed). The four copies of the contract (invoice plan §3.11c table) each gain the CREDIT_INVOICE entry and the new key return_reason; the existing contract tests keep them equal.

Company Settings › Advanced › Printing gains a third tab, Credit Invoice, beside Sales Order and Sales Invoice — the same checklist, no preview.

3.5 What happens to a returned item — Back to stock or Write off (owner, 5 Oct 2026)

Where it is stored. Per line: the existing ft_sales_detail.action_for_returned_item (RESTOCK · WRITE_OFF). Per item: the item's "When a customer returns this item" value (item.default_return_action, RESTOCK · WRITE_OFF, empty = not set) — added by the Item module, not by this plan.

What the line starts with — handling an empty item value — the first valid value (RESTOCK, WRITE_OFF, or PROMPT at store / company level); null, an empty string or an unknown word counts as not set and falls to the next level:

1. the item's value, when it is set — empty, NULL, or the column not there yet (the Item module has not shipped it) all count as empty and fall to 2;
2. the store's RETURNED_ACTION_CONTROL;
3. the company's RETURNED_ACTION_CONTROL (shipped RESTOCK);
4. nothing valid anywhere → RESTOCK (what the stock function does with an empty action today, F:4533).

PROMPT ("ask the cashier") at level 2 or 3 above means no pre-fill: the line starts empty and the user must choose. A service / non-stock item is always Write off (shown greyed, "Not a stock item").

Who decides. The user changes it per line on step 1 (a small select in the line, plus Set all to: Back to stock · Write off above the grid). It is saved with the draft, shown read-only on Review & send and on the view page, and can be changed until the return is submitted (Edit on Draft / Rejected). An approver sees it before approving.

What Complete Refund does with it.

No stock adjustment document is raised for a write-off: the goods never came back into stock, so taking them out again would count the loss twice.

Labels the user reads (no codes on screen): Back to stock · Write off · Use the store setting. The two existing field-option names are relabelled in core/field_options.py and field-options.ts.

Database: nothing new in this plan — ft_sales_detail.action_for_returned_item already exists and fn_api_inventory_set_sale_stock_movement already honours it. /returnable reads the item value only once the Item module's column exists (B0b); until then every item counts as empty.

Not touched: the till (§9A R10) and Stockable — both read item with explicit column lists (v2-sellable-api item_query.py:75, v2-stockable item_table.dart), so a new column is ignored there until they choose to read it.

3.6 Loyalty points and gift cards — not in this round (Revision 5)

Why out. The grill review (6 Oct 2026) found that a Back-Office invoice never gives loyalty points (no PTS_AWARDED / ft_loyalty_trans write anywhere in the Back-Office backend; points are given only by the till sync, v2-sellable-api sales_query.py:4176) and never sells a gift card (insert_sales_detail always writes item_entity_type = 'ITEM', sales_commit_repository.py:367). A Back-Office return is always against a Back-Office invoice (R3), so there are no points to take back and no sold card to void. Building it now would be code that never runs.

The rules stay decided for later (owner, 5 Oct 2026 — R14, R15), to apply when the invoice module starts giving points or selling gift cards:

• Points: take back the points for what came back, with the till's maths, never below zero (customer_loyalty_card.active_pts, COALESCE as the till does); one PTS_DEDUCTED row.
• Sold gift card: returnable only when never used (total_amt_redeemed = 0); at Complete Refund the card is voided (GIFTCARD_STATUS_VOIDED, core/constants.py:45) with one Voided ft_giftcard_trans row.

A gift card used as payment on the invoice is a different thing and is covered: V3 refuses a refund of a tender that is not refundable.

4. API

backend/app/api/sales_returns.py, prefix /api/sales-returns (main.py:353).

backend/app/api/sales_invoices.py

backend/app/api/company_settings.py — PATCH /print-options accepts doc_type = "CREDIT_INVOICE".

Item routes (backend/app/api/items.py) — create / update / detail / list carry default_return_action (optional, is_valid_option; same permissions as today).

v2-sellable-api report module — print_options.py gains the CREDIT_INVOICE defaults, required set and return_reason; receipt_renderer.py resolves options for CREDIT_INV; sales_document_receipt.html gains the credit-invoice title, the original-invoice line, the refund block and the return-reason line. POST /report/{report_type}/html already covers receipt types (invoice plan §3.11).

Every write body: ConfigDict(extra="forbid"). Every error uses the ApiResponse envelope with data.reason.

5. Permissions (RBAC v2)

Note: sales.return.approve existed once and was dropped as an unused leaf by 20260505_0700_drop_return_credit_approve.py; the new seed re-adds it (ON CONFLICT DO NOTHING) and says so in its docstring.

Migration: one reversible seed db-postgresql/migrations/tenant/versions/2026MMDD_0100_seed_sales_return_approve_permission.py in the shape of the invoice's 20260925_0100_seed_sales_approve_permissions.py — .approve and .delete: Backoffice Admin and Store Manager true. down_revision = the current tenant head at build time (alembic -n tenant heads; the chain has forked before), not a revision copied from this plan. Frontend: the code in the permission constants; usePermissions().can(...) on each button; route guards unchanged.

Store scope: every read narrows to effective_store_ids; every write calls require_record_store on the return and on the original.

6. Screens — the mockups, page by page

Source: mockup/return-bo-step-form-footer.html, mockup/return-print-options.html, mockup/return-print-email-formats.html. They are copies of the invoice mockups, so everything in ../invoice-bo/plan.md §6.5 "Common to every page" holds: 36 px fields and buttons (40 px on a phone), the pinned footer with the steps on the left and the buttons on the right, status pills from status-badges.ts, lucide icons, Title Case labels, no dialogs, no side panels, plain words.

6.1 Sales Invoice — where "Return Items" appears

• Row menu (Sales Invoices list): "Return Items" (Undo2) under a separator, only on Completed and on Returned with qty left.
• View page footer: on Completed, Back · Return Items. On Returned with qty left, the same.
• Hidden on Draft, Approval pending, Approved, Rejected, Voided, on a Returned invoice with nothing left, and on an invoice older than the return limit (V3) — the owner still sees it. On an invoice paid with a non-refundable tender the form opens with the red line "This invoice was paid with Gift Card, which cannot be refunded." and nothing can be sent.
• Linked Documents on the invoice view page lists its returns (Ref, Date, Status, Refund total); row click opens the return.
• Opening it goes to the return step form with step 1 filled and locked to that invoice (/sales/return/new?original={sales_id}).

6.2 Sales Returns list (DataTable)

• Breadcrumb Sales › Return — it ends at the section and does not repeat the title "Sales Returns" (owner, 6 Oct 2026), the same rule as the step form (§6.3).

• Title "Sales Returns", subtitle "Items customers brought back, and the money paid back to them.", Export, Settings, New Sales Return (Plus, primary; sales.return.manage) → /sales/return/new with no invoice: step 1 opens on the invoice list (§6.3). Owner, 5 Oct 2026, Revision 4 — brings back the button removed in Revision 3 (8).
• Columns: Transaction Date · Ref. No · Status · Original Invoice ("—" for a till return without a receipt) · Store · Customer · Return Reason ("Several reasons" when the lines differ; the filter matches a return when any line has that reason) · Refund Method · Refund Total · Written-off Cost (only with the cost permission) · Total Lines · Source Type · Created By · Updated Date · actions (pinned).
• Quick filter: Status — the approver's way to find returns waiting (Approval pending); there are no notifications (§1.2). Every column sorts; the filter row as the invoice list.
• Row menu: View · Edit (Draft / Rejected) · Submit for Approval (Draft / Rejected) · Delete (Draft / Rejected, sales.return.delete) · Approve / Reject (Approval pending) · Complete Refund (Approved) · Void Return (Approved) · Print · Print with options · Send Email (the last three on Completed / Voided only).

6.3 New / Edit — the step form

Page header (owner, 6 Oct 2026 — the standard's title + subtitle, docs/standards/step-form.md row 12; title kept; the breadcrumb ends at the section — Sales › Return — so it never repeats the title (owner, 6 Oct 2026: "it still redundant"). The invoice and order forms repeat it today; apply the same rule there for one look across the app (AppLayout.tsx, the form sub-routes)): New Sales Return with the subtitle "Pick the invoice, then choose what comes back and how the customer is refunded."; on Edit, Edit Sales Return CI-… with "Change what comes back or how the customer is refunded, then send it for approval."

Footer: steps 1 Invoice & Items › 2 Refund › 3 Review & send · Back · Save draft (once an invoice is picked) · Next / Submit for Approval · RM ….

Why one step (owner, 5 Oct 2026): the Invoice step alone held one search box and, once picked, a small read-only block — it looked empty, and the user could not see what was on the invoice until the next step.

• 1 Invoice & Items — no invoice yet (New Sales Return from the list). Search first, never a browse grid (owner, 6 Oct 2026, Revision 6). One panel Select the Invoice to Return holding only: the field Invoice Ref. No, customer name or phone (required mark, placeholder "e.g. SI-12/BO/2609-0006, Restoran Nasi or 012-345") with a Search button beside it, and the hint "Type at least 3 characters, then press Search or Enter. Only completed invoices with items left to return, inside the return limit, are found." Nothing is listed before a search — no grid, no recent invoices. Typing does not search by itself; Search or Enter does.
• Layout (owner, 6 Oct 2026: "the right side looks empty"): the search and its results take the left two-thirds; the right third holds a Before you search card — Use the receipt (where the Ref. No is printed), No receipt? (search by name or phone), Within N days (the return limit; the owner can return older), Already on the invoice? (open it and press Return Items). On a phone the card moves under the search. Under the field (owner, 6 Oct 2026: "below the search have empty space"): before any search a dashed placeholder fills the space down to the card's height — a search icon, "Search for the invoice to start", "The invoices found show here. Pick the one the items were sold on to see its items." The results, the too-short line and the no-match box take its place.
• Fewer than 3 characters → red line "Type at least 3 characters of the invoice Ref. No, customer name or phone." and no call to the server.
• No match → a dashed box "No invoice found for "…". Check the Ref. No, customer name or phone. Draft, voided, fully returned and too-old invoices are not found."
• Matches → "N invoices found. Pick the one the items were sold on." and a pick list (not a table): one card per invoice — Ref. No (bold, primary) with its status pill, the customer under it, the date · store under that; on the right the total and "n units left to return"; a chevron. The whole card is the button; the first card takes the focus after a search, so Enter on it picks. At most 8 cards; more matches → "N invoices found — showing the first 8. Type more to narrow it down." The list holds only invoices the user may return: Completed, or Returned with qty left; inside LIMIT_SALES_RETURN_IN_DAYS (the owner sees older ones too, V3); in the user's stores (require_record_store); Back-Office invoices only (R3); at least one refundable line (V21).
• Next with no invoice → the field turns red with "Search for the invoice the items were sold on, then pick it.", error toast, focus (step-form §8). Save Draft stays greyed until an invoice is picked. Footer Back reads Back to List. The data comes from GET /api/sales-returns/returnable-invoices?search=… (§4), which requires a search of 3+ characters.
• 1 Invoice & Items — invoice chosen. Top: the invoice summary card: ref (link), date, store, customer, sales rep, paid with, total. Change on the card (new return from the list only) clears the pick and goes back to the search (empty results) — lines, reasons and choices are cleared. Opened from the invoice's Return Items, or editing a saved return: no Change — the invoice is locked; footer Back reads Back to Invoice on a new return from the invoice. Under it, on the same page, the items grid: No · Item Code · Item Name · UOM · Sold · Already Returned · Can Return · Return Qty · Unit Refund (read-only) · Refund · Reason (select of the five Sales Return reasons, empty until chosen) · What happens to it (Back to stock / Write off, §3.5); above the grid Return all, Reason for all lines (one select that fills every returned line — a line can still be changed on its own) and Set all to: Back to stock · Write off; serial line → the Serial pick page (tick boxes of the serials sold); batch line → pick from the sold batches. Under the grid, the invoice's summary layout (invoice plan §6.5 Items): a short note on the left (Unit Refund is what the customer paid per unit; cash refunds round to 5 sen), and on the right the summary box — Total Net · a Tax group with one row per rate ("SST 10.00% · 2 lines", "No tax 0.00% · 1 line") and Total Tax · Rounding (only when not zero) · a rule · Refund Total in bold. Next and Submit are never greyed (step-form standard, docs/standards/step-form.md §8–9; owner, 5 Oct 2026). Pressing Next checks the step: what is missing gets a red border (aria-invalid) and a short line under it ("Choose a reason", "Choose one", "Choose how the refund is paid back."), an error toast "Some details are missing" names the first problem, and the first missing field gets the focus. A mark goes away as soon as the field is filled. Submit for Approval checks every step and opens the first one with a problem, marked the same way.
• Rejected return opened for Edit: the red Rejected banner above step 1 with the manager's reason (the last workflow_status_log.remarks), who and when — as the invoice form shows it.
• Lines that cannot be returned: a non-refundable line shows "Cannot be returned", greyed, no Return Qty box (V21).
• 2 Refund. The reasons in one line ("Damaged goods × 2 lines · Wrong item × 1 line", read-only — changed on step 1), the line "n items go back into stock at <store> · m are written off", Refund method (only the store's refund methods, V9; empty until the user chooses — no pre-selection; hint under it "Only payment methods set up for refunds at this store are listed. The invoice was paid with Cash RM 120.00."; Next with none chosen marks it red), Reference no. (optional; required for a card method, with the line "Refund the card on the terminal first, then enter its reference."), Note (printed on the credit invoice when "Document note" is on). Totals card on the right.
• 3 Review & send. Every step read-only with Edit links (the items with their What happens to it), the totals card, primary Submit for Approval.
• After Submit for Approval (owner, 5 Oct 2026 — the invoice's rule of 1 Oct 2026): no success page and no dialog. The return is saved, the app goes straight to the return's view page (status Approval pending) and shows the standard success toast — toast.success, the green filled toast of components/ui/sonner.tsx — "Sent for approval — Sales Return CI-…." with "A manager approves or rejects it." If the save works but the send fails, the view page opens on the Draft with an error toast saying it was saved but not sent (as SalesDocumentPage.tsx does for the invoice). Save draft keeps its own rule: back to the list with a success toast.

6.4 Sales Return view page

• Breadcrumb names the page, not the document (owner, 5 Oct 2026, Revision 4): Sales › Return › View Sales Return (Edit: Edit Sales Return). The ref is shown once, in the page title — as the app already does (AppLayout.tsx sub-route fallback: "View <page>"). The same rule on the invoice and sales order view pages.
• Header: ref · status pill; date ("Created" until Completed — decision D) · store. Top-right icon-only buttons: Print (Printer) · Print with options (SlidersHorizontal) · Send Email (Mail) · Audit (History). Print, Print with options and Send Email show on Completed and Voided only.
• Footer section steps: Details · Refund · Customer.
• Details: Return Info grid (original invoice link, return reason — the one reason, or "Several reasons", sales rep, created by) · Returned Lines (with Reason and What happens to it — Back to stock / Write off) · Summary · Linked Documents.
• Refund: method, amount, reference; "Paid out when the return is completed." until then; after, "Refund paid on <date>".
• Footer actions — Draft / Rejected: Edit · Submit for Approval; Approval pending: Reject · Approve; Approved: Void Return · Complete Refund; Completed / Voided: Back only. Delete (Draft / Rejected, sales.return.delete) on the left of the footer. Reject and Void open the reason card first. On a return whose card was already refunded on the terminal, the Reject / Void / Delete card shows "The card was already refunded on the terminal (ref …). Sort the money out with the customer — this does not undo the card refund." (C1). An Approval pending / Approved return whose refund changed shows the amber note of V13a above the details. Empty reason on the card: pressing Reject / Void Return marks the box red with "Write the reason", shows the error toast "Some details are missing" and puts the focus in the box — the same rule as Next (§6.3); the button is never greyed.
• Audit: the invoice's day-grouped timeline — Created · Submitted for approval · Approved · Rejected · Refund completed · Voided.

6.5 Print with options page (/sales/return/:id/print)

> Mockup note: the two print mockups always show one sample return (CI-12/BO/2609-0002), whichever row was clicked; ‹ Back opens that return's view page. The real page shows the return it was opened from.

The invoice's SalesPrintOptionsPage with kind = "return": breadcrumb Sales › Returns › CI-… › Print with options; title "Print credit invoice"; the checklist of §3.4b on the left with the counter "7 of 12 included"; the live A4 credit invoice on the right, sticky; Copies, Stamp each copy, Remark for this print, Save as the company default; footer ‹ Back on the left, Download PDF · Send e-mail · Print credit invoice on the right.

6.6 Mobile (≤ 767 px)

As the invoice: everything stacks, grids scroll sideways with the actions column in view, the step strip collapses to "Step 1 of 3 — Invoice & Items", the view page's section circles stay tappable; on the print page the preview moves under the checklist.

7. Files

Backend — changed: api/sales_returns.py (new routes, §4); api/sales_invoices.py (/returnable, linked returns); api/company_settings.py (CREDIT_INVOICE doc type); services/sales_commit_service.py (create_return → draft, original required, D1–D5); services/sales_lifecycle_service.py (VALID_TRANSITIONS per doc type, _NOUN gains CREDIT_INV, paid-in-full gate skipped for a return, Complete Refund, original → RETURNED); services/sales_return_service.py (receipt / preview / print-options / e-mail with print_options); services/sales_document_email.py (credit-invoice wording); repositories/sales_commit_repository.py (get_original_sale_for_return status filter, open-return qty, sold serials); repositories/sales_return_repository.py (list / detail fields); models/sales_creation.py (CreateReturnRequest), models/sales_return.py (SendEmailRequest.print_options); core/sales_doc_semantics.py (predicate §2.3); core/permissions.py (SALES_RETURN_APPROVE, SALES_RETURN_DELETE); core/print_options.py (PRINT_TYPES gains CREDIT_INVOICE, :45; print_type_for_doc_type, :87) and core/data/company_settings_default.json (CREDIT_INVOICE, return_reason).

Backend — review pass additions: models/print_options.py (PrintType Literal, :17, and its assert against PRINT_TYPES, :20; DocPrintOptions.CREDIT_INVOICE, beside SALES_INVOICE at :89; PrintOptionsStored.return_reason); services/print_options_service.py (get_document_print_options handles SALES_ORDER / SALES_INV only and raises "Unsupported document type" for CREDIT_INV today, :40-48 — add the CREDIT_INV branch); repositories/company_settings_repository.py (update_print_options, :160, accepts CREDIT_INVOICE); services/sales_return_service.py (new assert_receipt_access(), modelled on sales_invoice_service.assert_receipt_access, :492); services/sales_lifecycle_service.py (delete_document for CREDIT_INV); repositories/sales_document_repository.py (delete_document_rows also deletes the ft_sales_parent_child row); repositories/sales_commit_repository.py (get_returnable_lines / bump_qty_returned join the header on company_id; more columns and insert_sales_detail params, D6; is_returned on the original line); services/sales_commit_service.py (D7 maths, rounding, calculation token, time limit, tender rules, decision A payment row, decision D re-date); the BO payment readers of §2.3 (sales_collection_repository.py, business_day_repository.py, exchange_item_report_repository.py).

Backend — the line action: core/field_options.py (relabel ft_sales_detail.action_for_returned_item: Back to stock · Write off); repositories/sales_commit_repository.py (/returnable reads the store / company RETURNED_ACTION_CONTROL, and the item value once it exists). No item files change in this plan.

Backend — new: services/sales_return_write_service.py (edit, calculate) if sales_commit_service.py grows past its size.

Frontend — new: pages/sales/SalesReturnFormPage.tsx (the step form; reuses SalesFooterBar, TrackingEntryPage, ReasonCard, SalesAuditTimeline); pages/sales/components/ReturnInvoiceStep.tsx, ReturnItemsStep.tsx, SerialPickPage.tsx.

Frontend — changed: App.tsx (routes /sales/return/new, /sales/return/:id/edit, /sales/return/:id/print; /sales/new-return redirects), SalesReturnPage.tsx (list columns, row menu with Delete), SalesReturnDetailPage.tsx → the view page (or SalesDocumentViewPage with a return mode), SalesDocumentListPage.tsx / SalesDocumentViewPage.tsx (Return Items on Completed / Returned-with-qty-left), SalesPrintOptionsPage.tsx (kind = "return"), lib/constants/print-options.ts (CREDIT_INVOICE, return_reason), lib/api.ts (return receipt / preview / print-options / send-email with print_options), pages/company/tabs/AdvancedSettingsTab.tsx (Printing › Credit Invoice tab), hooks/use-sales-creation.ts, lib/constants/sales-lifecycle.ts (error words), lib/constants/field-options.ts (the relabel). SalesReturnCreatePage.tsx is removed.

Other apps: v2-sellable-api/src/modules/sales/sales_query.py (bo_not_a_sale_sql, §2.3, and the three payment readers listed there); v2-sellable-api/src/modules/report/report_query.py (query_payment_summary); v2-sellable-api/src/modules/report/print_options.py, renderers/receipt_renderer.py, templates/sales_document_receipt.html (§3.4b). v2-pos-client: none — a Completed Back-Office return reaches the till like any Completed Back-Office document.

Database: the seed migration (§5); the company_settings_json column comment names CREDIT_INVOICE. No new table, no new column; ft_sales_detail and the stock function unchanged.

8. Tests

Backend (backend/tests/unit/):

• api/test_sales_return_lifecycle_api.py — V2, V5, V6, V10, V11, V12, V14 on every route.
• services/test_sales_return_from_invoice.py — V3 (Draft / Approved / Voided original refused), V4 (two open drafts over the sold qty), V8 (tampered price ignored), V10 (no original refused), D3 (notes carry no code).
• services/test_sales_return_complete.py — V13 all-or-nothing; original → RETURNED with one log row; qty_returned bumped; one negative payment row; stock movement called once.
• services/test_sales_return_tracking.py — V7 serial not on the invoice, serial returned twice, batch split.
• services/test_sales_return_reason.py — V6: every returned line needs a valid reason; the line's voided_or_returned_reason_code / _notes / _by / _datetime are written; header = the shared reason, NULL when mixed; the list filter finds a return by any line's reason.
• services/test_sales_return_action.py — V19: the pre-fill order item (when set) › store › company › RESTOCK; an empty item value falls to the store; a store value of null, "" or an unknown word falls to the company; PROMPT gives no pre-fill and Submit is refused until each line has one; a non-stock line is saved as WRITE_OFF; every saved line has a non-NULL action.
• services/test_sales_readers.py — a CREDIT_INV at Draft / Approval pending / Approved / Rejected / Voided is not a sale.
• services/test_sales_return_print.py — V18: print-options returns the CREDIT_INVOICE entry over the defaults and the three required keys; send-email forwards print_options; bad print_options → 400; the e-mail says "Refunded", never "Amount due".
• models/test_company_settings_seed.py — the seed, model and frontend defaults agree with CREDIT_INVOICE added.
• services/test_sales_return_money.py — D7: a tax-inclusive invoice (3 units, 6% inside the price, a cart discount) returned 1 then 2 units: the refund total equals what the customer paid for those units (the invoice header grand total share, not total_amt_after_tax), the two returns add up exactly, no cent drift; the same tax-exclusive; the last return of the invoice refunds exactly what was paid less earlier refunds; a Cash refund rounds with _rounding_of(company), a card refund does not.
• services/test_sales_return_rules.py — V3 return limit (31 days refused, owner passes, store value overrides company, null store falls to company); V3 Gift Card tender refused; V9 tender not enabled for refund at the store, stored-value tender, a split-paid invoice refunded in full by one flagged method, card without reference; V21 non-refundable line; V23 stale / foreign calculation token.
• services/test_sales_return_draft_payment.py — decision A: the Draft writes one negative payment row with method and reference; edit replaces it; Complete Refund re-checks it (amount changed → 409 REFUND_CHANGED) and writes no second row; decision D: Complete Refund moves doc_trx_date and the payment trx_date to today, keeps doc_ref_no, the lines are found through the new date window.
• services/test_sales_return_delete.py — V22: Draft deleted with its lines, payment row, parent link and log; Approved refused; the deleted Draft's qty is returnable again.
• services/test_sales_return_lines.py — D6: the return line carries the invoice line's barcode, category, UOM, cost, service flag; total_cost / total_profit signs as the till; sales rep shown, header sales_rep_user_id NULL.
• services/test_sales_return_tenancy.py — V1: another company's ref_sales_detail_id / original refused on get_returnable_lines, bump_qty_returned, create; original in another store → 403 on the non-replay path; return /receipt of another store → 403.
• services/test_sales_return_complete.py also: original locked before the open-return re-sum; store with no default stock location → 409 before any write; original line is_returned set when fully returned.
• services/test_payment_readers.py — a return Draft's payment row is absent from sales collection, business-day collection, the exchange report and the v2-sellable-api payment summary.
• python ops/ci/scripts/check_workflow_registry.py exits 0.

Report service (apps/v2-sellable-api/tests/report/test_receipt_renderer.py): each CREDIT_INVOICE key hides or shows its element; the three required keys cannot be turned off; the return reason prints as words; the original invoice number always prints; a till CREDIT_INV with no print_options uses the company setting.

Frontend (frontend/src/pages/sales/__tests__/): Return Items shows only on Completed / Returned-with-qty-left; Return Qty over Can return stops Next and marks the box; the returns list shows New Sales Return; /sales/return/new without an invoice opens the invoice list; nothing is listed before a search; fewer than 3 characters → red line and no request; Search / Enter runs it, typing alone does not; results are a pick list of at most 8 cards; the search matches Ref. No, customer name / code and phone, and a Voided / Draft / over-limit invoice never shows; Pick fills the card and the items, Change clears them back to the search; Next with no invoice marks the search box; step 1 shows the items under the invoice card; Set all to changes every line; Next stays enabled and marks every returned line with no reason or choice, toast + focus on the first; Next and Submit are never disabled; footer buttons per status; Print / Print with options / Send Email only on Completed / Voided; the print page counter reads "7 of 12"; npm run typecheck, the status-badges drift test.

• services/test_sales_return_revision5.py — V13a: refund_check on the detail of an Approved return; approve, then complete another return of the same invoice → Complete Refund 409 REFUND_CHANGED with both totals; Submit of a changed Draft → 409 and the new amount saved on edit. R7: void an Approved return → its lines' voided_or_returned_reason_code unchanged, the held qty released (Can return back to the old figure), the invoice status unchanged. H3: PUT /cashier on an Approved return → 409; on a Draft it never writes sales_rep_*. H4: invoice detail counts only Completed returns as returned; Draft / Rejected shown as "On an open return"; Voided not shown. H2: Submit of a Draft saved the day before does not fail on an expired token.
• Frontend: the amber note and Void and Start Again (new return filled with the same lines); Complete Refund on a changed return shows the error toast and scrolls to the note; the card warning on Reject / Void / Delete of a return with a card reference; the refund method hint.

8.1 Acceptance

1. A Completed invoice shows Return Items in the row menu and on the view page; a Draft / Approved / Voided invoice does not.
2. A return cannot take more than sold − returned − already on other open returns — on the screen and on the API.
3. The refund price equals what the customer paid per unit, discounts and tax included, whatever the request sends.
4. A return with no original invoice is refused by the API; the screen has no way to start one.
5. Nothing moves before Complete Refund: no stock, no money, not in reports, not on the till.
6. Complete Refund in one transaction: refund paid, Back to stock lines back in stock (Write off lines not), return Completed, invoice Returned, log rows written.
7. Every returned line carries Back to stock or Write off, pre-filled from the item, then the store, then the company setting; the user can change it until submit.
8. The author cannot approve (the owner can); void only at Approved.
9. A Completed return prints, prints with options and e-mails exactly like a Completed invoice: same page, same preview, same copies / remark / company default; the attached PDF uses the same choices.
10. The refund of a line equals its stored invoice amounts pro-rata, on tax-inclusive invoices too; the last return leaves no cent behind.
11. An invoice past the return limit (owner exempt), paid with a non-refundable tender, or a non-refundable line cannot be returned.
12. The refund method and reference are kept on the Draft and count in no report until Completed; the credit invoice is dated the Complete Refund day.
13. A Draft or Rejected return can be deleted and frees its qty.
14. pytest, npm test, npm run typecheck, check_workflow_registry.py pass.
15. A refund that changed after approval cannot be paid at the old amount; the view page says what changed, why, and offers Void and Start Again, which opens a filled new return at the new amount.
16. Voiding or deleting a return leaves the original invoice as it was: same status, its items returnable again; the return keeps its line reasons and the void reason.
17. The refund method list shows only the store's methods flagged for refund; one method pays the whole refund, whatever the invoice was paid with.
18. Rejecting, voiding or deleting a return whose card was already refunded shows the card warning with the terminal reference.
19. New Sales Return opens on a search field only; no invoice is listed until the user searches with at least 3 characters, and the matches are a short pick list.

9. Open points — for the owner

9A. Decisions needed

Closed during the build (owner, 6 Oct 2026): a refund is never more than the items picked, and never more than is left of what was paid on the invoice (§3.2).

Closed in Revision 5 (owner, 6 Oct 2026, after the grill review — grill-review.md):

• C1 — card refund timing: keep the current flow. The cashier refunds the card on the terminal and keys in everything (method, reference) on the Draft; approval comes after. Accepted risk: a Rejected, Voided or Deleted return may already have its card refund paid. So the Reject / Void / Delete card on a return with a card reference shows "The card was already refunded on the terminal (ref …). Sort the money out with the customer — this does not undo the card refund." The reference stays on the return and in its audit.
• R7 — keep everything. A void keeps what void_document writes today on the header (voided_or_returned_* = the void, sales_lifecycle_service.py:313-319); the return reason stays on each line (ft_sales_detail.voided_or_returned_reason_code, untouched by the void), so both are kept with no new column. The original invoice is put back as it was: a void (Approved only) or a delete (Draft / Rejected) happens before Complete Refund, so qty_returned, is_returned, stock and the original's status were never changed; the qty the return was holding is released at once (V4 counts only open returns), "Already returned" on the invoice counts Completed returns only, and Linked Documents shows the return as Voided. Test: void an Approved return → the invoice's Can return goes back to its old figure and its status is unchanged.
• R13 — no cap per method. The refund method list shows only the store's payment methods flagged for refund; one method pays the whole refund (V9).
• Refund changed after approval — say it on screen (V13a).

Closed in Revision 4 (owner, 5 Oct 2026, after an outside check of Square, Lightspeed, Odoo, Shopify) — moved out of this round by Revision 5 (§3.6); kept as the rule for later: R14 — loyalty points given on the invoice are taken back at Complete Refund for what came back, never below zero (§3.6). R15 — a gift card sold on the invoice can be returned only when it was never used; the card is then voided (§3.6).

Closed in Revision 3 (review pass, owner, 5 Oct 2026): A — the refund method and reference are kept on the Draft as its ft_sales_payment row, replaced on edit, re-checked (not created) at Complete Refund, hidden everywhere by the §2.3 rule until Completed. B — return time limit = the existing setting LIMIT_SALES_RETURN_IN_DAYS (store, else company, shipped 30); past it Return Items is hidden and the API answers 409 RETURN_WINDOW_PASSED; the owner is exempt (V3). C — a coupon used on the invoice stays used after a return (§1.2). D — the credit invoice is dated the day Complete Refund is pressed; doc_ref_no keeps the Draft's number (§2.1).

Closed in Revision 3: R12 (owner, 5 Oct 2026) — one reason per return line; units of one invoice line that came back for two reasons go on two returns, or the user picks the main reason; no line split. R4 (damaged goods) — replaced by the per-line Back to stock / Write off choice with an item default (§3.5).

Closed in Revision 2: R1 and R2 (who may raise a return without an invoice, and its refund price) — that path is out (§1.2). R5 (refund methods) — any store payment method except gift card / store credit, no owner question left.

Note for the invoice plan (not this plan): on a tax-inclusive Back-Office invoice ft_sales_detail.total_amt_after_tax is stored as net + tax although the tax is already inside the price (sales_batch_split_service.py:108-117), so line totals do not add up to the header. Fix it in the invoice module; this plan does not read that column for an inclusive invoice.

Also confirm: the Sales Returns list still shows till returns taken without a receipt (Original Invoice "—", Source Type "Till") — they are real returns in the books; the Back-Office only cannot create one.

Also confirm: "Return Items" on a Returned invoice that still has qty left (this plan says yes — otherwise a second part return is impossible).

9B. Build order

Progress (6 Oct 2026): B0 done — Redy-20260910-BO-Invoice merged into Redy-20261005-Sales-Return (merge commit 11de7bae1; the return PR can merge only after the invoice PR). B1 built, not committed: D1–D7, V3 (limit, tender), V9, V21, V23 (POST /api/sales-returns/calculate; the token carries the priced refund) — services/sales_return_rules.py (new), create_return / _price_return / calculate_return, repository reads scoped through the header; tests tests/unit/services/test_sales_return_b1.py. Still Completed in one step until B2. Added in build (owner to confirm): a return that would pay back more than is left of what was paid on the invoice is refused, 409 REFUND_OVER_PAID — an invoice not paid in full cannot be refunded in full. Not in B1: per-line reason and Back to stock / Write off (B2a), batch split across two batches (B3), V4 open-return hold (B2).

B2 built, not committed (6 Oct 2026): a return is saved as a Draft with its refund row (decision A); PUT /{id} edit, DELETE /{id}, submit / approve / reject / void / complete, status-history; _TRANSITIONS_BY_DOC adds Approved → Completed for returns only; Complete Refund locks invoice then return, re-prices (V13a), re-dates (decision D), bumps qty, Completed before stock, invoice → Returned; V4 open-return hold; refund_check on the view data (never raises); predicate hides a CREDIT_INV at Approved in the BO and v2-sellable-api payment readers (readers with an "include voided" toggle use BO_NOT_A_SALE_PREDICATE_H_KEEP_VOIDED); sales.return.approve / .delete + seed 20261006_0100_seed_sales_return_permissions.py; PUT /cashier limited (H3); invoice "returned items" count Completed returns, open ones carry return_status (H4). Tests test_sales_return_b2.py, test_return_phase_b2_readers.py. Ship B2 together with B3 — until the B3 screens exist, a Back-Office return can be saved but not sent, approved or completed from the UI. Known, not changed: returns write no ft_sales_item_tax rows (as before).

B2a + B3 built, not committed (6 Oct 2026): a reason and Back to stock / Write off per line (_line_choices; header reason = the shared one, else none; non-stock always Write off; pre-fill default_return_action: item › store › company RETURNED_ACTION_CONTROL › Back to stock, "ask" = none); field-option labels Back to stock · Write off; GET /api/sales-invoices/{id}/returnable now gated by sales.return.manage and carries holds, free serials, pre-fill, paid with, sales rep; new GET /api/sales-returns/returnable-invoices. Screens: SalesReturnFormPage.tsx (step form, invoice list + search, items, serial pick page, refund, review; edit and "start again" pre-fill), the view page (SalesReturnDetailPage.tsx, footer actions per status, Reject / Void / Delete cards, card warning C1, refund-changed note V13a), the list (New Sales Return, row menu per status), Return Items on Back-Office invoices. SalesReturnCreatePage.tsx removed; /sales/new-return redirects. Not yet: Print with options for returns (B4), list columns Return Reason / Refund Method / Refund Total / Written-off Cost, per-rate tax rows in the form summary. The invoice list is bounded by the company's return limit (a store with a longer own limit is refused on nothing but may miss rows in the picker).

B4 built, not committed (6 Oct 2026): CREDIT_INVOICE print options in all four contract copies (BO core + models + seed JSON, frontend constants, report service), return_reason a key on every type (false on order / invoice); credit invoice forces company_address, unit_price, totals_breakdown on and deliver_to, discount, einvoice_qr, bank_details off. Routes /receipt (now store- and status-checked), /receipt-preview, /print-options, /send-email with print_options, all through assert_receipt_access (Completed / Voided only). Report service: CREDIT INVOICE / VOIDED CREDIT INVOICE sheet, original invoice number and date, Unit Refund, "Refunded by …", reasons as words, serials in the item note, positive amounts; till credit invoices (non-BIR) now print on the same A4 sheet (§9A R8). E-mail: "Credit Invoice {ref} — {company} — RM… refunded", "Refunded" card, credit_invoice_{ref}.pdf, voided wording. Screens: Print with options page for returns (/sales/return/:id/print, "7 of 12 included"), Print with options on the view page and list, Company Settings › Printing › Credit Invoice tab. B5 (predicate in both apps) was done inside B2. All phases B0–B5 built. Note for the owner: till e-receipts now also show serial numbers (the shared receipt query returns them).

10. Decisions that shaped this plan

• Same document type as the till (CREDIT_INV / REFUND), no new table, no new column — a return reads the same in every report whichever app wrote it.
• From an invoice only (owner, 5 Oct 2026) — a return without a receipt stays at the till, where role access POPC_NEW_SALES_RETURN already controls it. Two ways in, both to one invoice: New Sales Return on the list (pick from the invoice list) and Return Items on the invoice (Revision 4).
• The Back-Office moves money only at Complete Refund. A card refund is the exception: it is done on the terminal first and keyed in on the Draft (owner, 6 Oct 2026, C1). The Draft records the method as its payment row, hidden until Completed (owner, 5 Oct 2026, A).
• Return limit = the till's own setting LIMIT_SALES_RETURN_IN_DAYS, owner exempt (owner, 5 Oct 2026, B); coupons stay used (C); the credit invoice is dated the Complete Refund day (D).
• Refund = what the customer paid for the line, from the stored amounts pro-rata (inclusive invoice: total_amt_b4tax; exclusive: total_amt_after_tax) — never recomputed from unit prices (D7).
• Back to stock / Write off per line (owner, 5 Oct 2026) — reuses the column the till already writes and the stock function already reads. The item's own default is the Item module's; this plan only falls back when it is empty.
• Invoice and Items on one step (owner, 5 Oct 2026) — the Invoice step was too empty.
• Print and e-mail are the invoice's (owner, 5 Oct 2026) — one page, one contract (DOC_PRINT_OPTIONS), one more document type CREDIT_INVOICE.
• Mockups copied from the invoice mockups — the owner asked for the same layout, not for options.

11. History

• Revision 6 — 6 Oct 2026. Owner: (1) review the New Sales Return page — mockup checked page by page: the leftover per-item "Write off" pre-fill (Revision 3, item field out of scope) removed so lines follow the store setting; "Total Net" → "Refund Before Tax" as in the built app; the duplicate search icon removed. (2) Search first, no browse grid on step 1 — §1.1, §6.3, §4 (search required, 3+ characters, 8 per page), §8, §8.1. Plan and mockup only; the built SalesReturnFormPage.tsx and GET /returnable-invoices follow in the next build step.
• Revision 5 — 6 Oct 2026. Grill review (grill-review.md: 1 critical, 8 high) answered by the owner: (1) C1 keep the current flow — card refunded and keyed in on the Draft, approval after; warning line on Reject / Void / Delete; (2) R7 keep everything — return reason on the lines, void on the header; the original invoice stays as it was and the held qty is released; (3) R13 no cap per method — only the store's refund-flagged methods; (4) H6 the changed refund is explained on screen (V13a) with Void and Start Again. Plan fixes from the review: V10 rewritten for the invoice list; V23 token on create / edit only; PUT /cashier limited; invoice "Already returned" counts Completed returns only; §3.6 loyalty / gift cards moved out (code that would never run); /returnable-invoices row joined to its table. Mockup: refund-changed note on CI-12/BO/2609-0004 with Void and Start Again; card warning on Reject / Void / Delete; refund method hint; Delete label; "BO" → "Back-Office".
• Revision 4 — 5 Oct 2026. Owner: (4) the breadcrumb on a view / edit page no longer repeats the ref shown in the title — it reads View Sales Return / View Sales Invoice / View Sales Order / Edit …, in the return mockup and the invoice + order mockup (§6.4). (3) after an outside check, R14 and R15 closed — loyalty points are taken back at Complete Refund, the till's maths, never below zero; a sold gift card returns only when never used and is then voided — new §3.6, §2.0 rows updated. Correction: Revision 4's first draft said "the till does not take points back" — it does (sales_query.py:4176). (1) review again every table and column a return touches — §2.0 checked against the DDL: ref_sales_detail_id is indexed (T:7740), FK list extended (T:8436, e-invoice tables), new "Also touched" table (serial / batch stock paths, bundles, shift id left NULL, e-invoice, loyalty, sold gift cards, PSP, shipments), promo rows contradiction removed, backend cites marked as on the unmerged sales branch; R14, R15 added; (2) a New Sales Return button on the Sales Returns list again, and step 1 shows the list of sales invoices with a search as before — §0, §1.1, §4 (GET /api/sales-returns/returnable-invoices), §6.2, §6.3, §8; Change on the invoice card for a return started from the list. Undoes Revision 3 (8). Plan and mockup only.
• Revision 3 — 5 Oct 2026. Owner: (14) Refund method is never pre-selected; Next with none chosen marks it red, error toast, focus; (13) Wording: Credit Note → Credit Invoice everywhere (owner, 5 Oct 2026) — screen text, sheet title CREDIT INVOICE, e-mail subject, file name credit_invoice_….pdf, print-options key CREDIT_INVOICE; kept: LHDN's own term "credit or refund note" and the existing file credit_note_report_repository.py; (12) Second check, the same day: the refund for a tax-inclusive invoice is taken from total_amt_b4tax (the stored total_amt_after_tax adds the tax twice on an inclusive invoice — invoice-side fault reported); tax and promo rows move date with the lines on Complete Refund; reporting date stated; "same shape as the till"; (10) The summary under the items table uses the invoice's layout and rows (Total Net, Tax by rate, Total Tax, Refund Total); (9) Next / Submit are never greyed — pressing them checks the step, marks the missing fields in red, shows an error toast and focuses the first (step-form standard §8); (8) No "New Sales Return" button on the returns list — a return starts from the invoice's Return Items only; the invoice search and Change link on step 1 removed; (7) The item setting is out of scope — removed the item column, Item › Settings row, item import and §6.7; the plan only handles an empty item value (store › company › Back to stock). The step 1 items table was tidied (one toolbar row, shorter headers, everything in view); (6) A reason per return line (the till already stores it per line) — §2.1, V6, §3.4b, §6.2–6.4, R12; the header reason is derived. (5) After Submit for Approval, go straight to the return's view page with the standard success toast — the "Submitted for approval" page is removed; every success toast in the mockup now uses the green success style; (1) review every table and column a return touches — new §2.0 (found: ft_sales_detail.action_for_returned_item already exists and the stock function already skips a WRITE_OFF line; ref_sales_detail_id has no index; two existing gaps noted). (2) A per-line choice of what happens to the returned item — Back to stock / Write off, §3.5, V19. (3) A default per item — new column item.default_return_action, Item › Settings row (§6.7), item import column. (4) The Invoice step looked empty — joined with Items into 1 Invoice & Items (§6.3); three steps now. R4 closed; R10, R11 added; B2a added. Plan and mockup only. (11) Review pass (5 Oct 2026): owner decisions A–D written in and closed in §9A (refund method kept on the Draft as its payment row, return limit LIMIT_SALES_RETURN_IN_DAYS with owner exemption, coupons stay used, credit invoice dated the Complete Refund day with its lines re-inserted); refund maths replaced (D7: tax-inclusive bug, per-unit cart share) with the last-return rule and Cash-only rounding; D6 line data copied from the invoice; Delete for Draft / Rejected (sales.return.delete, V22); till refund controls (non-refundable tender, store refund methods, per-method cap, card reference; R13 added); non-refundable items (V21); tenancy joins and require_record_store on the original (D1, V1); is_returned on the original line; header money, cost and profit at Draft vs Complete; sales rep shown but not written; V13 lock order and stock-location check; calculation token (V23); print plumbing and a new assert_receipt_access for returns (§7, V18); seed down_revision at build time; no notifications; payment readers listed (§2.3); Rejected banner on Edit; reason-card validation; stale cites fixed (create_return :1603, VALID_RETURN_REASON_CODES :92, S9 :1662, DOC_SUB_TYPE_REFUND :45, F:3616, RETURNED_ACTION_CONTROL cites, company-level credit-invoice prefix); D2 rewritten. Red-team pass the same day (no critical / high): added D5 (a return line carries no cost today, so a write-off loss was invisible) and V20, the Written-off Cost column, the "first valid value" rule with a final RESTOCK, and "the till ignores the item default until R10" in the summary.
• Revision 2 — 5 Oct 2026. Owner: (1) no return without an invoice — removed the "Without an invoice" card, the sales.return.unlinked permission, the no-invoice reason, the Return Type tag, §1.3 and §3.3, R1, R2 and R5; the API now requires the original invoice (V10). (2) Follow the agreed Back-Office screen standard — the return mockup was brought back in line with the current invoice mockup. (3) Print and e-mail the same as the sales invoice — §3.4 rewritten (three ways out, statuses, e-mail wording, the CREDIT_INVOICE checklist with defaults and required rows), new routes in §4, V18, B4, R8, R9, two new mockups (return-print-options.html, return-print-email-formats.html). (4) Plan and mockups only; nothing built. Red-team pass the same day: added the Voided credit invoice and e-mail wording (§3.4a), fixed the seed file name and eight line numbers, the print pages' Back now opens the return's view page.
• Revision 1 — 25 Sep 2026. First plan. Checked against the code and the schema by two verifiers; fixed from them: the stock step must run after the status is Completed (V13), the currency source, the transition map must become per document type (§3.1), the exchange stub answers 500 not 501, the sales.return.approve history. Research: code map of today's return (Back-Office, till, v2-sellable-api) and an outside check of unreferenced returns (Shopify, Lightspeed X-Series, SAP Business One, Odoo 18, LHDN credit note rules) — kept for reference; that path was removed in Revision 2.