Customers
Who your customers are, and what they still owe you
A customer list is easy. A customer list that also answers “how much is outstanding, across which orders, after which refund, and is the third instalment late” is a different piece of software. Akkad keeps the record simple and puts the difficulty where it belongs — in a money ledger built so that every balance on screen can be recomputed from the rows underneath it.
A customer record holds what you actually need to reach someone and send them something: name, email, a primary and a second phone, city, two address lines, a postal code, the courier city and region they map to, and a free JSON field for anything specific to your business. It also carries a cached balance — which, as the rest of this page explains, is a convenience and never the authority.
The list itself is built for the way merchants actually look people up: half-remembered, from the wrong field, in a hurry.
01
One record, eight ways to find it
Search runs across all eight fields at once, so you can type a fragment of a second phone number or a street name and still land on the right person.
Search that does not ask which field
Name, email, both phone numbers, city, both address lines and the postal code are searched simultaneously. Nobody has to remember which box the number went into two months ago.
Filter by tag or by registration
The list filters by tag and by whether the customer has a storefront account, on top of the free-text search — so “everyone I labelled wholesale who has never signed in” is a two-click question.
Two queries, not two hundred
Enrichment — tags, account state, balances — is fetched in two batch queries for the whole page rather than one per row. A customer list stays fast at the size where lists usually stop being fast.
The registered filter is computed org-wide
Whether you have any registered shoppers at all is answered across the whole organisation, not across the visible page. The filter chip does not vanish just because no registered customer happens to be in the first twenty rows.
Shopper accounts heal themselves into the CRM
Storefront accounts are linked to their customer record on read, repairing anyone who signed in before that linking existed. There is no migration to run and no reconciliation screen to sit through.
Placeholder names are cleaned up
Old synthetic names — an email address used as a name, or the literal word “Customer” — are healed back to empty, so the app falls through to showing the email or phone instead of something that reads like a bug.
02
Tags are yours. The account badges are not.
Tags are merchant-defined labels in the style people already know from their phone: a name of up to fifty characters and a colour, unique within your organisation, applied to as many customers as you like. Setting a customer's tags replaces their whole set in one write, which is how a tag editor should behave — you look at a list of labels, you tick the ones that are true, and that is the new truth.
What tags are not is the Registered, Google and Apple badges you will also see on the list. Those are derived from whether that person has a storefront account and how they signed in. Keeping them separate matters: a derived badge must never be something a colleague can hand-apply, or it stops meaning anything. Your tags describe your relationship. The badges describe a fact about the account.
03
The debts ledger
One row per movement of money
Almost every debt bug in almost every system comes from the same root cause: a balance stored as a number, then edited. Somebody corrects a figure, somebody else recalculates a total, and six months later the merchant and the software disagree about what a customer owes — with no way to establish who is right. Akkad has one row per movement of money and treats those rows as the only truth. Every total is a plain sum of them.
Amounts are signed
Positive means collected, negative means refunded. There is no separate refunds table and no special case in the arithmetic — a balance is a sum, in one direction, with nothing to get wrong.
Rows are appended, never edited
A refund is a new negative row, not a correction of the original. The history of what actually happened stays intact and readable. A row can still be deleted when it records money that never moved — that is a data-entry correction, not an accounting one.
The balances you see are caches
The amount paid on an order and the balance on a customer are written only by the debt service, always in the same transaction as the ledger row. They exist so a list can render quickly, and nothing more.
Anything arguable is recomputed
A statement, a receipt, the debtors list — anything a merchant might put in front of a customer and defend — is calculated from the ledger rather than read from the cached column. If a cache ever drifted, it could not reach the document that matters.
04
How a balance is derived
Six decisions that turn a list of rows into a number a merchant can rely on.
| Concept | Rule | Why |
|---|---|---|
| Payment methods | Cash, card or bank transfer, recorded per row | The method travels with the money, so a mixed settlement stays legible later. |
| Payment status | Derived — unpaid, partial or paid — never stored independently | A status that is computed cannot contradict the rows it is computed from. |
| Rounding tolerance | Comparisons use a tolerance of 0.01 | Floating-point arithmetic cannot hold 0.1 exactly. Without a tolerance an order settles to “almost paid” and stays there forever. |
| Refunded | A merchant-set label, preserved rather than recalculated | When a ledger nets to zero the software must not quietly relabel a refund as unpaid. The merchant said refunded; that stands. |
| Closed years | A payment cannot be dated into a closed accounting year | Reopening the year is the deliberate escape hatch. Backdating into closed books should require a decision, not a keystroke. |
| Cancelled and returned orders | Excluded from debts entirely | An order that did not happen is not money owed. |
Debts ship switched off, and that default is load-bearing
Payment status has always defaulted to unpaid. So the first merchant to switch debts on without thinking would open the app to every order they ever created, presented as an enormous fake debt — and would reasonably conclude the software was broken. The feature is therefore off until you turn it on, and the writes are refused by the server with a clear error rather than merely hidden in the interface. A gate that only hides a button is not a gate.
05
Who owes you, and what you hand them
Three views over the same ledger, each answering a different question.
The headline number
A single outstanding total across the whole business — the figure you want on a dashboard, not buried three screens deep.
The debtors list
Who owes you, biggest first, searchable, up to a hundred per page — and aggregated live from the orders themselves rather than from the cached column. Walk-in and counter sales with no customer attached are gathered into their own section so they are visible instead of invisible.
The customer statement
One customer, every unsettled order and every payment against them, in one document. This is the view you turn a screen around to show somebody, which is exactly why it recomputes rather than trusts a cache.
06
An agreement, not a second ledger
“Five hundred thousand down, then two hundred thousand a month for six months” is a common way to sell in this market, and it is the kind of arrangement software usually models badly — by inventing a parallel set of money records that then has to be kept in step with the real one.
An Akkad installment plan holds no money. It records the agreement: the order total snapshotted at the moment you shook hands, the down payment, how many instalments, how far apart they fall, and when they start. Every actual payment still lands as an ordinary row in the same ledger as everything else. There is one place money lives, and the plan is a way of reading it.
07
How a plan is built
Five decisions, each of which exists because the obvious implementation loses a merchant's trust in a specific way.
- 1
Snapshot the total, take the down payment
The plan records the order total as it stood when the agreement was made, along with whatever was paid up front. Later edits to the order do not silently rewrite what the customer agreed to.
- 2
Split the remainder evenly, and put the odd amount last
Instalments are split evenly and rounded to whole units, with the leftover pushed onto the final row so the parts always sum back to exactly the financed amount. “Six times 33,333 is 199,998, but I am owed 200,000” is the kind of discrepancy that ends a customer's confidence in one sentence.
- 3
Space the due dates by a fixed interval
Dates step forward by a set number of days from the start date — thirty by default, which is what people mean by monthly here. Fixed intervals deliberately avoid calendar-month arithmetic, so there is no end-of-month rule to argue about in February.
- 4
Answer “is instalment three paid” by pouring, not by matching
The order's total collected amount is allocated in a waterfall: the down payment first, then row one, then row two, and so on. Nothing can drift out of step, because there is only ever one number being sliced into parts.
- 5
Derive each row's state, in precedence order
Paid, partial, late, upcoming. A row is only late when money is still missing and the date has already passed — a row settled a week after its due date is simply paid, not permanently marked against the customer.
08
Rules that keep a plan honest
One plan per order, replaced rather than stacked
Renegotiating writes a new agreement over the old one. Two overlapping plans on the same order would mean two answers to the same question, and there is no correct way to choose between them.
Sixty instalments maximum
Five years of monthly payments is the ceiling, as a guard against a mistyped figure. A plan with six hundred rows is a typing accident, not a deal.
Installments require the debts ledger
Plans are only available when both installments and debts are switched on, because a plan with no ledger beneath it would be a schedule nobody could pay into.
Reading a plan is three queries, not three per plan
Serialisation is batched, so a customer with a long history opens at the same speed as one with a short one.
09
Four signals, and why the device is the anchor
Fake cash-on-delivery orders are a real cost in this market: stock reserved, a courier dispatched, a fee paid, nobody at the door. A block list matches on any of four signals, and they are not equally useful.
Device ID
An identifier stored in the browser. Cheap to check, and cleared the moment someone knows to clear it — useful, but on its own only a speed bump.
Device fingerprint
A hash of hardware traits, which survives cleared storage and private browsing. This is the anchor signal, because it identifies the machine rather than a value the machine is willing to forget.
IP address
Kept, but treated as weak. Carrier-grade address sharing on Iraqi mobile networks means one blocked address can quietly take real customers with it.
Normalised phone number
Also kept, also weak on its own. Spam orders rarely carry an honest phone number, and SIM cards are the easiest of the four things to replace.
10
Spam control
Orders that never happened
When a blocked checkout is submitted, it does not fail. It receives a normal-looking success response — including a plausible order number, read from your counter without consuming one — and absolutely nothing is written. No order, no stock movement, no courier, no notification. A visible rejection would only teach the person on the other end to change device, change SIM, change network and try again, which is precisely the loop worth avoiding. Silence is the more effective answer.
Nothing is written, and no number is spent
The order number in the response is peeked read-only from the organisation's counter. Your real numbering is untouched, so your order sequence has no unexplained gaps in it later.
Tracking pixels stay quiet
Purchase events are suppressed for blocked checkouts, so fabricated orders never reach your advertising platforms. Otherwise a spammer would be actively teaching your ad targeting to find more people like them.
Every block records why it exists
A block row keeps the note, the order number that triggered it and who added it. Six months later it is still possible to answer why a particular device is on the list, and to remove it with confidence.
11
Questions
If balances are cached, how do I know the number I am reading is right?
Because the number you can argue about is never the cached one. Statements, receipts and the debtors list are recomputed from the ledger rows every time. The cached balance exists so a list of two thousand customers renders quickly, and it is written only by the same service that writes the ledger, inside the same transaction.
How do I record a refund?
As a negative row in the ledger. It is never an edit of the original payment, so the history shows what actually happened and in what order. Refunds also flow back out of your money-on-hand figures, which is what a refund physically does.
Why is the debts feature off when I start?
Because payment status has always defaulted to unpaid. Switching debts on without that default would present every order you have ever created as an outstanding debt. The gate is enforced by the server rather than the interface, so it cannot be bypassed by an out-of-date app.
Can I change an installment plan after the customer has started paying?
Yes — a new plan replaces the old one wholesale rather than stacking beside it. The payments themselves are untouched, because they live in the ledger and not in the plan. The new schedule simply reallocates the money already collected, top down.
Do the automatic Registered, Google and Apple badges count as tags?
No. Those are derived from the customer's storefront account and cannot be applied by hand. Tags are yours to define — a name, a colour, applied to as many customers as you want — and the two are kept deliberately separate so a derived fact never gets edited into a fiction.
What does a blocked customer see when they try to order?
A normal confirmation, with a plausible order number. Nothing is stored, no stock moves, no courier is called and no purchase event is sent to your advertising pixels. The point is to avoid teaching them which signal caught them, because the moment they know, they rotate it.
Related
Orders
The orders debts attach to — six statuses, the totals engine, editing and idempotent submission.
Money and reporting
Where collected payments land: one definition of “money moved”, driving both the cash box and the financial report.
Online store
Shopper accounts, checkout and the spam signals collected there before an order is ever written.
See it against your own catalogue
Start on the plan that fits, import your products from a spreadsheet, and have a working store, counter and order book the same day.
Free tier available. No card required to try. Import brings your existing catalogue with you.