Distributors hub¶
The hub at /app/distributor-hub is where a manager sets up and watches every wholesale house. It shows one card per Distributor record. Anyone with a purchasing or stock role can read it. Changing a switch or the order needs System Manager or Purchase Manager.
What a card shows¶
Across the top of a card sit the priority number, the house name, its provider code and the linked Supplier. A house whose provider code has no integration behind it is marked not registered in red, and its Test Connection button is disabled.
The four switches¶
| Switch | What turning it on means |
|---|---|
| Enabled | The house is in use. Everything else depends on this |
| Drop-ship | Orders may ship from this house straight to a buyer or their FFL |
| Stocking | You may raise restock orders into your own inventory |
| Poll | The system asks this house for order progress on a schedule |
A card with Enabled off is greyed. The switches save the moment you click them, and a failure puts the box back where it was.
The health line¶
| Item | What it tells you |
|---|---|
| Quantity feed | How long ago the live quantity heartbeat last arrived |
| Catalog | How long ago the catalog content heartbeat last arrived |
| Last order poll | When this house's orders were last polled. Shown only while Poll is on |
Any of these can read "never". When the provider itself cannot be reached, the health line is replaced by the error in red, and the rest of the card still draws.
The order and pricing line¶
Below the health line, a clickable summary reads as N draft, N in flight and N need attention. Clicking it opens the Distributor Order list filtered to this house. In flight covers Queued, Placed, Acknowledged and Partially Shipped. Need attention covers Hold and Error, and it turns red when it is not zero. Complete and Cancelled orders are history and are not counted.
Beside it, Markup rules gives the number of markup rules on this house, and the default markup percentage when one is set.
The buttons¶
| Button | What it does |
|---|---|
| Test Connection | Runs the provider's live probe and shows each check with a green, red or grey dot and a detail line. It is read-only and places no order |
| Open Settings | Opens the Distributor record, where priority, pricing defaults and markup rules live |
| Credentials | Opens the provider's own settings page, where the account numbers and keys are kept. Shown only when the provider has one |
| Catalog Service | Opens the catalog service health page for this house. Shown only when the house is fed by the catalog service |
| Add Distributor | At the bottom of the page. Asks which provider to use, then opens a new Distributor form |
Priority is changed with the small ↑ and ↓ buttons in a card's header. They appear once there is more than one house.
Priority and what it drives¶
Priority orders the cards, lowest number first, and that order is the order the system prefers. It sets the column order in the fulfillment planner and picks the default house when nothing else names one. Houses on the same number sort oldest first, so a never-ordered house at 0 sits at the top. Moving a card rewrites every house's priority as 1 through N, so the list is always a clean sequence.
Pricing defaults on the Distributor record¶
Open Settings takes you to the record where the money rules live.
| Field | What it does |
|---|---|
| Default Markup % | The tail of the pricing chain. Used only when no rule, no MAP and no MSRP produced a price |
| Default Rounding | How that fallback price is rounded: .99, none or whole. A matched markup rule uses its own rounding instead. Rounding never prices below the computed figure |
| Safety Buffer | Units held back from the published quantity, against a feed that is a few minutes behind. Defaults to 3 |
| Display Cap | The most you will ever publish, however much the house holds. Defaults to 5. A cap of 0 means no cap |
| Zero Stock When Feed Stale | When this house's heartbeat ages out, publish 0 rather than sell quantities nobody can verify. On by default |
The published quantity is the live quantity less the safety buffer, capped at the display cap, and never below zero.
Markup rules are a table on the same record. Each rule matches by Department or by Brand, and applies Markup % and Markup Flat together, so the price is cost times one plus the percentage, plus the flat amount. Each rule carries its own rounding.
The full order of precedence is a locked price on the listing, then a per-item markup override, then a brand rule, then a department rule, then the global default, which is MAP if there is one, else MSRP, else cost plus the default markup. MAP is a price source only. Nothing is ever lifted up to MAP or capped at it here.
Dropship Brand Policy¶
Some brands will not be drop-shipped to a consumer. Dropship Brand Policy is one record per Brand with a single choice.
| Policy | Meaning |
|---|---|
| Direct OK | Drop-ship is allowed, when the distributor also permits it |
| To Store | Procure into the shop first. Never ship direct to the buyer |
To Store is the default for a new policy record. The point is that a restricted brand stays sellable. It is bought in and passed to the customer rather than being taken off the store.
The Catalog Service page¶
/app/catalog-service shows the shared catalog service's own health on the left, beside what this site actually consumed on the right. The two columns are never merged, because the whole point is to see where they disagree. Each column states its own staleness thresholds. The page refreshes itself every 60 seconds, and Refresh forces a read.
Left column, the service¶
| Card | What it holds |
|---|---|
| Feed freshness (service) | Each feed with a green or red dot, whether it is fresh, stale or never synced, its age, and the threshold applied |
| Catalog contents (service) | Offers total and active, how many are in stock, product count by UPC, how many changed in 24 hours, the change sequence high-water mark, and when the next catalog run is due |
| Data quality flags (service) | Counts of catalog data problems such as a missing MAP, a missing image or an orphan UPC, plus discontinued and deleted counts. These count data quality, not service failures |
| Recent sync runs (service) | Failures in the last 24 hours, the last failure with its error class and source, and a short run history with finished time, row count and duration |
The panel also warns when ingest is switched off service-side for this house, or when the service does not recognize the house's code. If your API client does not carry the catalog operations permission, the panel says Catalog Service is not enabled for this site and the right column carries on regardless.
Right column, this site¶
| Card | What it holds |
|---|---|
| Our sync position | The change cursor, and how many SKUs sit behind it |
| Our feed watchdog | Quantity feed and catalog content, each fresh or stale with its own age and threshold, plus whether Zero stock when feed stale is on |
| Listings on this site | Counts by status, how many have never synced, how many are more than 24 hours stale, how many carry a sync error, and the newest and oldest sync times. Open listing list opens them |
| Routing flags | The same four switches as the hub card, read-only, with a link back to the hub |
What a stale feed means on the sales floor¶
A stale quantity feed means the numbers on your web store are older than the watchdog is willing to trust.
Selling what you cannot verify
While Zero Stock When Feed Stale is on, a stale feed publishes 0 for every listing of that house. Drop-ship items go out of stock on the web store until the feed recovers. That is the interlock working. Turning it off means the store keeps offering quantities nobody can confirm, and the failure mode is overselling a gun you do not have.
The staleness watchdog runs every fifteen minutes. It alerts once per house, and where that house has opted in, it pushes the listings to zero.
The two columns can disagree, and that is worth reading. A fresh service feed beside a stale local watchdog points at your own sync. A stale service feed points upstream, and there is nothing to fix on this site.