Receipt verification queue

CRM · Receipt verification queue

Moderation workspace for customer-uploaded purchase receipts: review the image and OCR’d data, validate (which also redeems the entitlement), reject with a reason, un-reject, and navigate the queue with previous/next.

Area	CRM
Routes	crm.receipts · crm.receipts.index
Centre modules	tickets
Staff levels	root · admin · manager · crmmanager · crmoperator · weboperator
Models	campaign · commerce · receipt
UI label	title.header.crm.receipts / menu.navbar.receipt.show
Coverage	5 use cases · 4 happy · 7 failure

Known issues (1)

• 🟠 Medium — Unknown receipt reject reason breaks the moderation panel

How it works

The richest state machine in the app. Seven receipt states (draft, pending, not-redeemable, redeemable, not-yet-redeemable, redeemed, rejected) each with a colour and a tooltip; eight reject reasons (duplicated, illegible, modified, other centre, out of period, out of store, over max amount, other) and seven automatic pending reasons explaining why the system could not decide (no code, no store, over 250 amount, not this centre, out of date, no amount, invalid date). isValidating/isSavingReject/isUnrejecting guard concurrent mutations, and previousReceipt/nextReceipt with isFirstSelectedReceipt/isLastSelectedReceipt make high-volume moderation keyboard-fast. canSeeModerator reveals who moderated a receipt. reprocessPendingReceipts re-runs automatic processing over the pending backlog.

Use cases

Why someone opens this (5)

• A moderator working through the overnight backlog of uploaded receipts.
• Rejecting a duplicate receipt with an auditable reason the customer can be told.
• Reversing a wrong rejection (unreject re-runs validation).
• Re-processing the pending queue after fixing a store’s configuration or campaign dates.
• Finding out which moderator handled a disputed receipt.

Path map

flowchart LR
    F(["Receipt verification queue"]):::feat
    F --> H1["Receipt validated"]:::ok
    F --> H2["Receipt rejected with a reason"]:::ok
    F --> H3["Rejection reversed"]:::ok
    F --> H4["Pending backlog reprocessed"]:::ok
    F -.-> X1["Validated but not redeemable"]:::bad
    F -.-> X2["Validation request fails"]:::bad
    F -.-> X3["Reject without a reason"]:::bad
    F -.-> X4["Unknown reject reason"]:::bad
    F -.-> X5["Reject save fails"]:::bad
    F -.-> X6["Embedded API errors"]:::bad
    F -.-> X7["Reprocess not permitted"]:::bad
    classDef feat fill:#157068,stroke:#157068,color:#ffffff,font-weight:bold
    classDef ok fill:#e3f1ea,stroke:#0d6b42,color:#0d4a2e
    classDef bad fill:#f7e6e2,stroke:#9a2d1c,color:#6e1f13

Happy paths

Receipt validated

1. Moderator opens the queue filtered to pending and selects a receipt.
2. Reviews the image against the parsed amount, date, code and store.
3. Clicks validate; isValidating blocks double submission.
4. The state moves to a validated state, validatedAt is stamped and the entitlement is redeemed.

Receipt rejected with a reason

1. Moderator picks a reject reason (required) and saves.
2. State becomes rejected, validatedAt is stamped and the reason is stored for the customer-facing explanation.

Rejection reversed

1. Moderator opens a rejected receipt and clicks un-reject.
2. unreject() delegates straight to validate(), so the receipt is re-validated in one step.

Pending backlog reprocessed

1. Moderator triggers reprocess on the pending set.
2. crm.receipts.reprocess-receipts-success confirms the job was accepted.

Failure paths

Validated but not redeemable

Cause — The receipt validates but the entitlement cannot be redeemed (campaign closed, limits reached).

What happens — receipt.validate.error-message-unable-to-redeem — explicitly states the receipt was validated but not redeemed, so the operator knows the two outcomes diverged.

Validation request fails

Cause — API error.

What happens — catch resets selectedReceipt.validatedAt to null and clears isValidating, rolling the optimistic update back.

Reject without a reason

Cause — rejectReason not set.

What happens — reject() only proceeds when a reason exists; the field is marked required.

Unknown reject reason

Cause — A stored rejectReason is not in the enum.

What happens — rejectReasons getter does .find(...).label without a guard, so this throws a TypeError and breaks the panel.

Reject save fails

Cause — API error.

What happens — catch resets validatedAt and leaves the previous state.

Embedded API errors

Cause — A 200 response that still carries data.errors.

What happens — throw data.errors.firstObject surfaces it into the catch chain.

Reprocess not permitted

Cause — canReprocessReceipts false for the role.

What happens — The action is hidden.

QA checklist

Tick these off while regression-testing this feature. The boxes are plain Markdown, so progress is visible in git diffs.

• ✅ Receipt validated
• ✅ Receipt rejected with a reason
• ✅ Rejection reversed
• ✅ Pending backlog reprocessed
• ⛔ Validated but not redeemable
• ⛔ Validation request fails
• ⛔ Reject without a reason
• ⛔ Unknown reject reason
• ⛔ Reject save fails
• ⛔ Embedded API errors
• ⛔ Reprocess not permitted

Implementation

• app/controllers/crm/receipts/index.js
• app/routes/crm/receipts/index.js
• app/enums/receipt-status.js
• app/enums/reject-reasons-receipts.js
• app/enums/pending-reasons-receipts.js
• app/abilities/receipt.js

Translation keys (27)

Key	English
title.header.crm.receipts	Receipts
menu.navbar.receipt.show	Verify receipts
receipt.status.draft	Draft
receipt.status.pending	Pending
receipt.status.redeemable	Redeemable
receipt.status.not-redeemable	Not redeemable
receipt.status.not-yet-redeemable	Not yet redeemable
receipt.status.redeemed	Redeemed
receipt.status.rejected	Rejected
receipt.validate.error-message-unable-to-redeem	The tickets has been successfully validated but could not be redeemed.
crm.receipts.reprocess-receipts-success	The tickets have been successfully reprocessed
receipts.reject-reason	Rejection reason
receipts.index.moderator-name	Moderator
receipt.state.duplicated	Duplicated
receipt.state.illegible	Illegible
receipt.state.modified	The receipt and the taken photo have not the same information
receipt.state.other-center	The receipt does not belong to this center
receipt.state.out-of-period	The receipt date is out of the activity period
receipt.state.out-of-commerce	Commerce does not belong to the campaign
receipt.state.over-max-amount	Maximum amount exceeded
receipt.pending.not_code	The ticket code could not be read
receipt.pending.not_store	The store name could not be read
receipt.pending.over_250_amount	The amount is greater than €250
receipt.pending.not_center	The center could not be read from the receipt
receipt.pending.out_of_date	The date could not be read correctly
receipt.pending.not_amount	The amount or the date could not be read correctly
receipt.pending.invalid_date	Invalid date

Related

• Same area — Customer list & filtering · Customer create & edit · Customer deletion with unsubscribe notice · Customer CSV export with column picker · Customer CSV import · Children CSV import · AI natural-language customer filter · Save current filters as a segment · Segment list, refresh & export · Segment builder with automatic tag actions · Segment categories · User tags (user types) · Customer receipts tab & ticket-stamp generation · Customer loyalty — raffle tickets · Customer loyalty — cards & stamps · Customer loyalty — rewards · Customer loyalty — coupon exchanges · Customer children (dependants) · Store list, filters & exports · Store create & edit · Store CSV import · Store labels (store types) · Customer action log (dormant)
• Shares data with — Activity editor (loyalty mechanics, rules & targeting) · Proposal editor (content, coupon, push, AI images) · Activity list & duplication · Activity report & PDF · Activity campaigns (programme grouping) · Push notification editor (scheduling, geofencing, deep links) · App button manager (MOFs) · Multicentre proposals
• Behind the same module — Customer loyalty — raffle tickets · Customer receipts tab & ticket-stamp generation · Activity editor (loyalty mechanics, rules & targeting)

---

Generated from doc/feature-inventory.json · id crm-receipt-moderation · commit 276788ca6