OCR Cash Bill

Turn a member’s photograph of a receipt from another business into loyalty points: the platform reads the image, matches the merchant and each line against reference data kept here, and a reviewer corrects the mapping, rejects fakes and duplicates and finalises the document. Nothing here posts a journal, touches stock or creates a supplier invoice; points are the only output, and none are awarded unless BigLedger has switched on the points subscription for your tenant.

Your job, and the screen for it

Overview

OCR Cash Bill is the back-office console for a receipt-to-points loyalty programme. A member photographs a cash bill issued by some other business — a partner shop, a franchisee running its own till, a kiosk beside your branch — and uploads it from the e-commerce storefront or in store. The platform runs the image through AWS Textract, turns the extracted text into a structured OCR Generic Document, matches the merchant and each line item against reference data the applet maintains, and — once a reviewer finalises the document — converts the matched lines into membership points on the member’s card.

This applet is where a reviewer looks at what the machine read, corrects the item mapping, rejects the fakes and the duplicates, and presses FINAL. It is the only screen on which any of that is visible.

Who needed it. A retail group whose members also spend at businesses it does not ring up — a partner kiosk, a franchisee on its own till — and who wants that spending to earn the same points. The receipt is the only evidence of the purchase, so the design is built around a person looking at the photo before anything is awarded: the machine reads, matches and flags, and FINAL is a human decision.

Where it fits

Screens and menus

Eight screens exist. Six are linked from the sidebar; two have no menu entry and are reachable only by typing their address.

Two broken links are visible in the chrome rather than the content:

• The shared settings sidebar shows Permission Wizard, Release Notes and Audit Trail; this applet has none of the three, so all three open a 404. (Permission Set, User Permission and Role Permission work.)
• Personalization → Field Settings opens a 404 — the screen exists only under Settings.

Configuration

Before you can use it

Applet settings

Settings › Field Settings. This applet does not use the shared Field Configuration screen that most document applets use — it has its own two-toggle screen, and both toggles change what the listing’s advanced search offers you rather than what it looks like. Both are off until somebody saves them, and an applet with no saved settings row behaves as though both are off. How settings are stored and who they apply to.

The first toggle, HIDE_CUSTOMER_ADVANCED_SEARCH, takes the Customer criterion off the OCR Generic Doc listing’s advanced search. It is a hide toggle and you can see what it did immediately, but one consequence is not on the screen: the criterion’s label, data type, form control and options are all deleted from the search model before the panel renders, so a saved search that used Customer stops filtering by it rather than warning you. Absent means shown — the consuming code simply does not take the branch.

The second changes what the panel can do, so it gets a row:

Both keys are read by exactly one component — the listing’s search panel. No other screen consults them, and neither reaches the server.

On the screen and doing nothing

Settings › Default Selection renders four controls — Default Branch, Default Location, Default Company and Default Timezone — and saves all four into the applet’s settings. No screen in this applet reads any of them. Picking a branch does fill Default Company from that branch’s company and Default Location from its main location, so the four values stay internally consistent; they simply have no consumer, and a new OCR document does not open pre-filled with them.

• The default time zone is the one to be careful about, because a time zone is the kind of setting a reader will assume is being applied to the receipt dates they are looking at. It is not applied anywhere.
• DEFAULT_BRANCH, DEFAULT_LOCATION and DEFAULT_COMPANY behave the same way. The only thing that reads them back is the settings screen itself, re-displaying what you saved. In particular, the branch the points are booked to comes from the points subscription, not from Default Branch.

Personalization › Default Selection is worse than unused: it cannot save. The first change to either drop-down fails with Cannot read properties of undefined in the browser console, and SAVE saves nothing. Treat the screen as absent.

Settings in other places that control this applet

Four validation thresholds are set per tenant by BigLedger support, not on any screen here (they are stored under OCR_GENERIC_DOC_VALIDATION). An absent or unreadable value falls back to the default.

The age is measured in 24-hour periods back from the moment the receipt is processed, against the receipt date — not in calendar days — so the default of 1 is tighter than “yesterday’s receipt is fine” suggests. A receipt dated more than a day in the future (a misread date, for instance) is rejected with the same Outdated receipt reason, which is misleading when you read it on the member’s complaint.

The monthly count goes by receipt date, not upload date: a receipt from the last days of the previous month, uploaded on the 2nd, does not count against this month. It counts every OCR document the member has with a receipt date in the month — ones rejected and ones a reviewer marked duplicate included. A photo the duplicate check caught does not make a new document, so it does not add to the count.

Three further thresholds are fixed and cannot be configured at all: the verification pass mark, how closely a merchant’s name must match an existing OCR Company, and how closely a scanned line must match an existing OCR Item.

Who can change what

Client-side permissions this applet defines: none. The registry holds zero active client-side permission definitions for applet code OCR Cash Bill, so neither Field Settings toggle can be reopened for one team and closed for another — each is an all-or-nothing tenant-wide switch, and anyone who can open the applet’s Settings section can flip it. If you need two groups of back-office staff to see different search panels, this applet cannot do it.

Pressing FINAL from the back office needs the OCR Generic Document update permission (or its owner or admin permission) on that document — set in Permission Set, User Permission or Role Permission like any other. FINAL is the decision that spends the programme’s money, so give it to the people who review, and not to everyone who can open the listing.

Fields

OCR Generic Doc — Main Details

The panel also shows Created Date, Updated By and the Uploaded Image (with rotate and zoom), the matched merchant as Company — changed through Select OCR Company — and a Status of Active or Close; choosing Close only asks you to confirm.

The six rejection reasons are fixed in the applet, not configurable: Outdated receipt, Non-related receipt, Duplicated receipt, Incomplete details, Exceeded Monthly Submission Limit (Max. 7 receipts per month), More than 1 receipt. The parenthetical “Max. 7” in the fifth is a label, not the limit — the limit is the configurable OCR_SUBMISSION_LIMIT_DURING_PERIOD above, and the label does not follow it.

OCR Generic Doc Line Item

Each line also carries its parent document number (read-only), the Item Code, Item Name and Description as the merchant printed them (upper-cased, from the matched OCR Item), free-text Remarks and a Status.

Lifecycle and effects

What posting does

The pipeline

    flowchart TD
    U["Member uploads a receipt photo<br/>(storefront or in store)"] --> SD["Scanned Receipt created<br/>Process Status PENDING_REVIEW"]
    SD -->|"now, or at the next scheduler pass"| TX["AWS Textract reads the photo<br/>result stored once"]
    TX -->|"straight away"| GD["OCR Generic Doc created"]
    GD --> M["Merchant match · item match · validation<br/>confidence, duplicates, limits, age"]
    M --> RV["Reviewer opens OCR Generic Doc<br/>checks the photo, corrects the mapping"]
    RV -->|FINAL| PP["The OCR posting job"]
    PP -->|"the subscription your tenant holds"| PB["Points job: evaluates the price book"]
    PB --> PT["Membership points lines<br/>lines written back · receipt APPROVED"]
    PT --> BAL["Member's balance and lots updated"]
  

What the server decides before a human sees it

Extraction. The OCR reads the receipt’s summary fields into the header and its item lines into the lines. Each value comes with the OCR’s confidence in it. The result is stored on the scanned receipt the first time and never requested again: if a photo was read badly, the reading does not improve by waiting — the reviewer corrects it, or the member photographs the bill again. Only the first receipt the OCR finds in the photo is kept, and a line on which it read neither an item code nor an item name is dropped before the document is made, so it never appears on the console at all.

Verification status. The document’s confidence level is the average confidence across the fields actually used. At or above a fixed pass mark it is PASS, below it FAIL — the same rule is applied independently to each line. Afterwards, if the extracted header total does not exactly equal the sum of the line amounts (or the header total is missing), a PASS is downgraded to FLAGGED. All of this is worked out once, when the receipt is read.

Merchant matching. The extracted merchant name is compared against the existing OCR Companies; if none is close enough, a new OCR Company is created.

Item matching. Each scanned line is compared with every OCR Item of that merchant, on item code, item name and unit price. The best candidate wins if it is close enough; otherwise a new OCR Item is created and linked. If the winning OCR Item is already mapped to one of your financial items, that mapping is copied onto the line immediately.

Duplicate detection. If the receipt number was read, a duplicate is an existing document with the same number and merchant at about the same time on the same date. If it was not, the match is on merchant, time, the same set of scanned item codes and an identical total. A match sets the scanned receipt to DUPLICATE / FAIL and reuses the existing document rather than creating a second one.

Two cases are never compared at all: a receipt whose date the OCR could not read, and one whose merchant it could not match. Both skip the check rather than fail it, so the same receipt uploaded twice and matched to two different merchants — or with its date unreadable both times — goes through as two receipts. Both searches also look only one hour either side of the receipt’s time, so a reprint carrying a later timestamp is a new receipt as far as the check is concerned.

Auto-rejection. Four rules run, and only the first one that fires is recorded: monthly submission limit reached; receipt older than the configured window or dated more than a day in the future; more than one receipt number and more than one date and more than one total detected (read as “more than one receipt in the photo”); or incomplete details — no merchant, no receipt date, or any line without a matched OCR item. Any of them sets the scanned receipt to REJECTED / FAIL and writes the reason onto the document.

The figures on the console, and the source of each

When a member or a colleague asks “where did this number come from?”, each figure on the console has one writer and one moment.

What FINAL actually runs

Pressing FINAL first finds the member: if the document has no membership card yet, the applet looks up the card by the uploading login and customer and records it on the document and the scanned receipt, then finalises. On both paths it also clears the rejection reason — finalising a rejected receipt erases the reason it was rejected.

FINAL is the approval, and it overrides a rejection. The points job does not read Process Status. A receipt the server rejected — or one you marked REJECTED or DUPLICATE — earns points the moment somebody finalises it, and the points job then sets its Process Status to APPROVED. That is the deliberate way to overrule an auto-rejection you disagree with (a bill the one-day window caught, for example). It is also why a receipt you mean to refuse is simply left un-finalised.

The server then starts the OCR posting job. That job does no work of its own: it starts each points subscription your tenant holds, passing on the company, branch and price book the subscription names. The subscription runs straight away; if it fails, the background scheduler retries it, up to five attempts in all, and then drops it without a message on any screen. One subscription is wired in the product:

• Membership points from the price book. It evaluates the price book’s rules against each document line — the merchant rule against the document’s OCR Company, and the item and category rules against each line’s mapped financial item — works out the points from the line’s amount or quantity, writes them back onto the line (type REWARD, currency, validity window, amount), creates one membership points line per matched receipt line, marks the document posted and finally sets the scanned receipt to APPROVED. All of that succeeds or fails together. The points line is dated with the receipt date, carries the subscription’s company and branch, and shows the job’s own name in the member’s Source column.

The document is marked posted even when no line matched. A receipt finalised with a line still at N/A, or matched to the wrong merchant, earns points only on the lines the price book did match — and because the document is now posted, pressing FINAL again changes nothing. Map every line, and check the merchant, before FINAL.

A second points job — one that copies a point amount already sitting on each line instead of reading a price book — is in the product, but no subscription links it to the OCR posting job, so a FINAL never starts it. If you have read elsewhere that OCR Cash Bill can award “without a price book”, that is this job, and it does not run.

One receipt, followed from photo to points

The scenario. GadgetSphere runs its member programme in a points currency GSPTS, and pays partner points on accessories bought at an independent accessory kiosk that trades beside branch GS-KV-03 on its own till. The price book on GadgetSphere’s OCR subscription has one price set for the kiosk: a merchant rule naming the kiosk’s OCR Company, a category rule for Accessories, and a POINT treatment of one point per ringgit of line amount, valid for 365 days. The subscription books the points to GadgetSphere Sdn Bhd, branch GS-KV-01.

14 March, 3.40 pm. A member photographs the kiosk’s cash bill in the storefront: a screen protector at RM 39.00, a USB-C cable at RM 25.00 and a clear phone case at RM 45.00 — RM 109.00.

What the console shows a minute later. One row on OCR Generic Doc: the kiosk as OCR Retailer, Verification Status PASS (the reading was confident enough, and the three lines add up to the RM 109.00 the OCR read as the total), Process Status PENDING_REVIEW, Posting Status empty, Membership Points 0.00. Open it: the first two lines carry financial items already, because the kiosk’s screen protector and cable were mapped on earlier receipts. The third, printed as PHONE CASE CLR, is new to the kiosk’s catalogue — the server created an OCR Item for it, and its Financial Item reads N/A.

The review. You compare the photo with the reading: the kiosk’s name and the date, the three prices, the total. Then on the third line you pick the clear phone case from your item master (in the Accessories category). That pick maps the kiosk’s PHONE CASE CLR to your item for good, and fills the same line on any other open receipt from the kiosk.

FINAL. Posting Status turns FINAL, the points job runs, and on reload Membership Points reads 109.00 in GSPTS, type REWARD; each line’s Point Amt reads 39, 25 and 45; Process Status reads APPROVED here and on Scanned Receipt. Nothing reaches the journal, stock or the kiosk’s account.

In Membership Admin. The member’s Point Transaction tab gains three REWARD lines dated 14 March — 39, 25 and 45 — whose Source reads OcrGenericDocMembershipPointsPriceBookProcessor; the Details tab’s Current Point Balance rises by 109; Points Expiry shows the lots ending on 14 March the next year.

Had you pressed FINAL first. The phone-case line would have matched no category rule, the member would have received 64 points, and the document would already be posted — a second FINAL changes nothing. The 45 points then go on by hand as a point adjustment in Membership Admin, with a remark naming the receipt’s doc no, by somebody allowed to adjust points.

Status model

The learning link

Setting a line’s Financial Item does more than fix that line. It maps the OCR Item itself to that financial item, and then back-fills every other non-FINAL line that carries the same OCR item and the same merchant and has no financial item yet. One correction can therefore change many open documents at once, and it is the mechanism by which a merchant’s catalogue becomes self-maintaining. The flip side: a wrong pick is copied just as faithfully, so correct a bad mapping on the OCR Item screen as soon as you spot it, before more receipts inherit it.

What success looks like: one receipt, three places that agree

Run this on your own tenant, on one receipt finalised this week; it takes about thirty seconds. (A demo tenant may have no OCR subscription, so the check is written for the tenant that runs your programme.)

1. The console. Open the receipt on OCR Generic Doc. Note Membership Points and each line’s Point Amt, and that Process Status reads APPROVED.
2. The member’s points history. In Membership Admin, open the member and the Point Transaction tab. Find the REWARD lines dated with the receipt date whose Source is the OCR price-book job. There is one per line that has a Point Amt, and their Points add up to Membership Points.
3. The member’s balance and lots. The Details tab’s Current Point Balance must equal the sum of the Point Transaction tab for that currency, and Points Expiry must show the lots with an end date after today.

Pass is three places that agree. When they do not:

What it will not do, and who does it instead

• It does not decide whether a bill is genuine. The machine reads and flags; the reviewer decides, before FINAL, by comparing the photo with what was read — the merchant, the date and time, every price, the total — and with what that merchant’s real bills look like. A reviewer who knows a merchant notices a doctored total that the duplicate check will not.
• It does not catch every repeat. A photo whose date or merchant was not read, or a reprint with a later time, passes the duplicate check. The reviewer searches the member’s other receipts (the advanced search’s Customer or Member criterion) before finalising a large one.
• It does not stop a reviewer finalising a rejected receipt. That is by design — FINAL is the override. Keep the people who review receipts separate from the people who set the price book, and have the programme owner read the month’s finalised receipts once a month: anything with a large Membership Points figure, and any receipt finalised after the server rejected it.
• It does not keep the rejection reason once a receipt is finalised. When you override a rejection, write down what the reason was and why you overrode it, in whatever log your team keeps, before you press FINAL.
• It does not settle a dispute with a member. When a member challenges a rejection, the programme owner decides, from the photo (it stays on Scanned Receipt) and the programme’s own rules. Overruled means FINAL; upheld means the receipt stays rejected and the member is told why.
• It does not take points back. There is no VOID. Points awarded in error come off as a negative point adjustment in Membership Admin, with a remark naming the receipt.
• It does not account for the points. Nothing here journals the cost of the points you have promised; finance carries that liability — see Points liability, and remember that every OCR point is booked to the one company and branch the subscription names.

Related applets

• Pricebook — the price book BigLedger names for the OCR points job is what converts a matched line into a number of points; its Calculation Logic is honoured by the points job and by almost nothing else. Unlike the till, the OCR job tests the price set’s OCR Company rule, and treats a price set with no single-line rule as matching every line.
• Membership Admin — the member’s card, the Point Transaction tab the points land on, the balance, and the point adjustment that repairs a short award.
• The points currency the price-book treatment names is defined in Membership Admin’s PTS CCY Module.
• Item Maintenance — the financial items OCR items are mapped onto; their categories are what a category rule tests.
• Scheduler — the background scheduler that reads a receipt queued with INSERT_TO_QUEUE and retries a failed points job. The OCR subscription itself is not a clock and does not appear there.

Troubleshooting

Related documentation

• Membership applets — the rest of the loyalty family.
• Membership module — where this sits in the product.
• Membership points and vouchers — the chain to walk when a member says points are missing.
• How work actually runs — subscriptions, queues and the background scheduler this pipeline runs on.