Serial Numbers: What the Balance Means and When It Moves

Four complaints turn up again and again on serialised stock, and they sound like four different faults:

the same serial sold twice, on two documents;
a serial showing quantity 2 when there is obviously only one of it;
a serial still available after the customer returned it — or still out after you took it back;
the till refusing a serial that is plainly on the shelf: Serial Number does not exist in this location.

They are one fact, and it is not on any screen. A serial number in BigLedger is not a flag on an item. It is a stock record in its own right, with a quantity balance, belonging to one item at one location. Almost everything surprising about serialised stock follows from that sentence.

This page is what a reader needs to predict the behaviour and check it. The ledger mechanism underneath — the sub-line rows, and why a trailing space makes a different serial — belongs to Costing internals and is not repeated here.

The record: one item, one location, one balance

When a serial first arrives, BigLedger creates a row for it holding the serial text, the item, the location, the company, a base quantity of 1 and a balance that starts at zero and then moves.

Read that list again for what is not in it. There is no single global record of serial ABC123. If the same serial exists at your Klang Valley branch and at your Penang branch, those are two rows with two balances, and a sale at one does not touch the other.

That is deliberate and it is the only shape that works for a multi-branch retailer: a serial is a physical object in a physical place, and “do I have it?” is always a question about a place. But it has consequences a reader should expect rather than discover:

A stock transfer moves a serial between two records. The outbound half takes it off the sending location; the inbound half puts it on the receiving one. If only one half posts — and the two halves are two documents — the two rows disagree, and the company-wide total is wrong by one while each location is individually consistent. That is the “serial asymmetry, in without out” shape.
Adding up serial balances across locations is a real total, not a duplicate count — unless exactly the above has happened.

Across the 26 of 90 live tenants that use serial numbers at all, this table holds about 9.2 million rows, median 31,000 per tenant. It is not a small corner of the product.

When the balance moves — posting, not saving

The balance does not move when you save a document, or when you finalise it. It moves when the document’s stock movement posts, which is a separate job that runs afterwards.

What happens then is worth knowing exactly, because it explains the “quantity 2” case:

The document line’s direction is read from its quantity sign. A line that brings stock in produces one +1 entry per serial. A line that takes stock out produces one −1 per serial.
A line whose net quantity is exactly zero produces neither. No entry, no movement, no change to the balance — on a line that still lists the serial on the document. This is the honest answer to “serial number not deducted from sales invoice” on a zero-quantity or zero-signum line.
Each entry is then added to the serial’s current balance. Added — the posting path is an increment, not a recalculation.

That last point is the whole of it. A balance maintained by addition is correct as long as every movement is added exactly once. Add one twice — a re-run, a re-posting, a document posted from two paths — and the serial reads 2 where it should read 1, and no amount of looking at the item will explain it, because the item’s own quantity was worked out differently.

There is a second path that re-derives the balance instead of nudging it. For one item at one location it re-reads every serial movement ever recorded, re-sums them from scratch, and corrects the serials whose stored balance disagrees — leaving alone the ones that already match. That is the repair, and it is what makes a wrong serial balance fixable rather than permanent.

A void puts the serial back, because the void writes negating movements and those carry the opposite sign into the same addition. See What a void undoes.

The four rules, in the words the screen uses

Whether a serial can be used on a document is decided by its balance, and the rule is different for each direction. These are the actual messages.

You are…	The rule	The message when it fails
Selling it	A record must exist for this item at this location with a balance above zero	Serial Number does not exist in this location
Receiving it	It must not already be held anywhere in this company with a balance above zero	Serial Number already exist in location … (and it names the location)
Receiving an inbound stock transfer	Exempt from the rule above — the serial is already in the company, sitting at the in-transit location	—
Taking a return	It must exist in the company, and its balance must be zero — you cannot take back something you are still holding	Serial Number does not exist in the system, or Serial Number already exist in location …

Three things follow that are worth having in your head before you meet them.

The selling rule is about the location, not the company. A serial sitting at another branch is not sellable here and the message is literally telling you so. If the goods are physically in front of you, what is missing is the transfer that should have moved them.

The receiving rule is about the company, not the location. You cannot receive a serial you already hold anywhere — which is what stops the same phone being booked in twice, and which is why the message names the location where it already is. Go and look there first.

The return rule is the one that surprises people. A return is refused while the serial still shows a balance, because a serial you never sold cannot come back. So “IMEI stuck in stock after return” and “the serial is still available after the return” are usually the same event seen from either side: the outbound movement never posted, so the balance never went to zero, so either the return is refused or — if it went through on a path that did not check — the serial ends up at 2.

The draft lock is a different thing, and it names its blocker

Alongside the balance there is a lock: while a draft document lists a serial, a row is written saying so. Its purpose is the obvious one — two people keying at once should not both grab the same phone — and it is worth understanding as its own mechanism because it behaves differently from the balance in four ways.

It is company-scoped, not location-scoped.
It is filtered by document type. A serial locked by a draft sales invoice is not released by something of another kind letting it go.
It is advisory, and consulted only when the screen asks for it. The lock is a check at the point of choice; the balance is the enforcement at the point of posting. That split is why the same serial can occasionally reach two documents from two different screens and only be caught when one of them posts.
The message names the document holding it — Serial Number is already locked by followed by the document’s short code and number. That is the most useful error message in this whole area: go and open that document.

Locks are cleared when the document finalises, when it is discarded, and when it is voided. A background sweep also clears any lock whose document has since reached final or discarded.

What nothing clears is a lock held by a document still sitting in draft. That is correct — a draft is a real reservation and releasing it behind someone’s back would be worse — but it has no expiry. A half-keyed invoice abandoned on a Friday still holds its serials on Monday, and the only thing that releases them is somebody finishing or discarding that document. When a serial is “stuck”, this is the first place to look, and the error message has already told you where.

The 30-second check

1. Ask which location. Every question about a serial is a question about a place. Read the message: if it says does not exist in this location, the serial is somewhere else, and the message for the receiving case will even name where.

2. Compare the balance against the movements behind it. The balance is a running total; the movements are the record. If they disagree, the total was added to twice or missed once, and the serial needs a rebuild — the balance is the thing that is wrong, not the transaction history.

3. If it is “stuck”, find the lock. The error names the document. Open it. It will be in draft.

4. If a serial reads 2, look for two inbound movements, not for a mystery. The commonest causes are a receipt posted twice and a transfer whose outbound half never posted.

What this will not do

It will not stop two locations holding the same serial text. Nothing enforces uniqueness across locations, and that is by design — the same serial can legitimately exist at the sending and in-transit locations during a transfer.
It will not tell you a serial balance is wrong. There is no report of serials whose balance disagrees with their movements. You find it one serial at a time, when a document is refused.
It will not treat two spellings as the same serial. The identifier is the text. A different case or a trailing space is a different serial — Costing internals has this and the sub-line mechanism.
It will not release a lock on its own. No timeout, no expiry, no nightly sweep for drafts.