Skip to main content

How a count works

A count goes through four steps. Only the last one changes any stock.

  plan                 prepare               count                    submit
────────────    ─────────────────────    ────────────────────    ─────────────────────────────
a count is      Stock Count builds       staff register          uncounted mandatory items
created for     the item list from       counted quantities,     become 0, the count is
one store,      the store's assortment   item by item and        published, and STP corrects
with a start    and STP's stock          location by location    the stock
date
                                         stock is NOT changed
                                         while counting
  CREATED  ─────────────────────────────▶  IN-PROGRESS  ─────────────────▶  COMPLETED
      │                                         │
      └────────────── deleted ──────────────────┴──────────────▶  DELETED

Status​

StatusMeaning
CREATEDThe count exists, nothing has been counted yet
IN-PROGRESSAt least one counted quantity has been registered
COMPLETEDThe count has been submitted and published. It cannot be reopened.
DELETEDThe count was abandoned. Nothing is published and the stock is not touched.

A count stays open until it is submitted or deleted. Its due date is a planning date — the day the store is expected to have finished — and passing it does not close the count.

1. Plan​

A count belongs to one store (business unit) and has a type, a start date (today or later) and optionally a due date. Counts are planned in four ways:

  • by store staff in the app — a full count of the store, or a quick count of one item;
  • by head office or an integration, through the API;
  • automatically, from a recurring definition that generates counts for many stores on a schedule;
  • automatically, as a count of suspicious items, for stores where it is switched on.

The type decides which items the count lists and what happens to items nobody counts.

The API accepts the request and applies it moments later​

⚠ Every write to Stock Count is asynchronous. Creating, editing, counting, completing a category and submitting all return 202 Accepted as soon as the request has been validated; the change is applied a moment later. A client that creates a count and reads it back immediately may get 404, and one that registers a quantity and reads it back immediately may see the old figure. Poll, or — for a count you created — supply your own stockCountId so you know what to look for. See The API.

2. Prepare the item list​

For counts that have a list, Stock Count builds it in the background:

  1. Candidates come from Product, Price and Promotion — the store's whole assortment for a full count, or the items matching the count's saved searches for a cycle count.
  2. STP's stock narrows them to the items that are worth counting: items that hold stock, or that have moved since they were last counted. An item STP has never had stock of is not listed — not even in a full count.
  3. An item is in only one open count per store. If another open count already lists it, it is left out of this one.

The details, including optional filters on stock state, are in Types of count.

When the list is built:

  • a count that starts today is prepared straight away, usually within seconds, though a very large store can take minutes;
  • a count that starts later is prepared on its start date, in the nightly run at 01:00 UTC;
  • while a count is open, its list is refreshed every night at 01:00 UTC. Items that have started to qualify since the day before are added — an item that received stock, or one released by another count that was completed. Nothing is removed from a list once it is on it.

While the list is being prepared the count reports itemsGeneratedDateTime: null, and the app shows Preparing items…. A value there with an empty list means the list was built and nothing qualified.

3. Count​

Staff register count lines: an item, a location, and the quantity found there. An item found in three places gets three lines, and the count adds them up. Registering a line for an item moves the count from CREATED to IN-PROGRESS.

Each line is stamped with the time it was registered in Stock Count, and that time is what decides how sales during the count are treated. See Counting while the store is open.

🛑 Nothing happens to the stock while counting. Counted quantities stay inside Stock Count until the count is submitted. A count can be open for hours or days — the stock figure the POS sees keeps moving with sales as usual, and the count is reconciled against it only at submission.

Marking a category as done​

Staff can mark an item category as done before the whole count is finished. At that moment every mandatory item in the category that nobody counted is registered as counted 0, and the category is closed. In the app this is the normal way to work through a store, aisle by aisle.

4. Submit​

Submitting closes the count. In one step, Stock Count:

  1. registers every mandatory item that nobody counted as counted 0 — see What happens to items nobody counted;
  2. marks the count COMPLETED;
  3. publishes the result as stc.public.event.stock-count-completed.v1 — except for a test count, which is never published.

A count that ends up with no lines at all — nothing counted, and nothing mandatory to set to 0 — is completed without publishing anything.

Once a count is completed or deleted, the API rejects further lines for it with 404.

What STP does with it​

Stock Transaction Processing subscribes to the event and corrects the sellable stock (SalesStock) for each counted item:

  • the quantities of an item's lines are added up across all locations;
  • the count is dated at the item's first registered line;
  • the new stock figure is the counted total plus every movement dated after that time — sales, returns, deliveries, transfers and corrections. Movements dated before it are already in what was counted.

The difference between the result and what STP had before is booked as a STOCK_COUNT transaction, so the gain or loss stays visible in the ledger. Why the count is dated at the first line, and what that means for counting during opening hours, is the subject of Counting while the store is open.

⚠ STP only applies counts for a tenant that has stock processing switched on — the Do enable PosLog processing setting, which despite its name gates every feed from Hii Retail services into stock. See STP configuration.

What an external system does with it​

Anything else — an ERP, a reporting system, a data warehouse — can subscribe to the same event through External Events. See Events, and Stock ownership for when an external system, rather than STP, should be the one that decides the resulting quantity.