The wholesale market

XGM_KERNEL=wholesale runs every market of the desk as a wholesale marketplace: regular FMCG products — single items, multipacks and bundles — bought from suppliers at a landed cost, shipped in with a lead time, held in stock and sold through the buy box against competing sellers. Everything else on the site (carts, checkout, payments, agents, the record, the console, owned goods and the exchange) works as it does on the platform's other markets.

One session is one simulated week: every rate below is per session.

The listings

About a thousand listings (the platform's item families) in twelve categories of different sizes, in the mix of a real wholesale seller's assortment — Grocery & Gourmet Food (190 listings), Beauty & Personal Care (165), Health & Household (125), Tools & Home Improvement (110), Arts, Crafts & Sewing (70), Office Products (60), Pet Supplies (60), Home & Kitchen (55), Patio, Lawn & Garden (35), Automotive (30), Sports & Outdoors (30), Baby Products (25). About 10 % of the listings are bundles of two or three products of the category and about 22 % multipacks.

The products are real FMCG SKUs: the built-in catalogue holds ~5,700 products of a real wholesale seller's assortment with their real titles, brands, product types, reference prices, size tiers and case packs. Their identifiers are not real: every ASIN, MSKU, FNSKU, UPC, supplier item number and part number (in the titles too) is lightly scrambled — deterministically and in its own format: an ASIN is still B0 and eight letters and digits, an MSKU still ASIN-SUPPLIER-SEQUENCE built on its ASIN's scramble (every MSKU of one supplier shares one code), a UPC still has a valid check digit and shares its prefix with the manufacturer's other products. No product brings its real sales, sellers or wholesale cost: those are the market's own (below). A listing is labelled by its product type ("Ground Coffee · GRO-0012") and owns a handful of the category's products of that type.

The product on a listing changes over time. Every product has a SKU in the market (GRO-0012-G7: the listing's seventh product), an ASIN and an MSKU, and a life of 300–1,200 sessions: it ramps up, sells, and at the end of its life phases out — over 16–60 sessions its demand fades, its reference price falls, sellers leave, and none of it recovers. Then the listing's next product takes over under a new SKU (a product that comes back is relisted under a new MSKU). A few listings in a hundred are phasing out at any time, and suppliers clear such products at deep discounts: a trap, since they will not sell again.

Sales follow the real assortment, category by category (all sellers together, per session): a few fast movers — the top tenth of a category sells from about 11 units a session (sports, tools) to 140 (grocery) and more, its top 1 % hundreds to a thousand — a median listing selling 3–9, and a long slow tail: about a fifth sell under one unit a session, many under one a month. Sales velocities are never published, in any form.

What a deal shows

The rank and its gate

Ranks are a real marketplace's: a listing is ranked among every product of its marketplace category — 1.7 million in Grocery, 7 million in Home & Kitchen — so a fast mover sits in the hundreds or thousands, the median listing around 100,000–400,000 and a listing that has not sold for months near the bottom. Every unit sold lifts a listing's fading sales score, silence lets it fade, and the score's rate of sales goes through its category's curve from sales to rank (the real category's: a listing selling what the category's q-quantile listing sells is ranked where its q-quantile listing is), set against the category's own season and the market's tide — a rank is relative: when the whole category sells more, nobody moves — with a little scatter from the rest of the category. Ranks move instantly; they are published through a gate: a listing selling at least 10 units a session lately is published at once (rank_as_of = the last closed session), a slower one a session late (rank_delay_tiers). GET /api/v1/markets/{id}/families/{cluster}/signals serves a listing's published series — rank, the session it is as of, the drops of that session, the sellers, the buy box price and the SKU — whether or not a supplier offers the listing this session.

Sellers and the buy box

A listing carries its category's typical crowd of competing sellers (5 in Grocery, 10 in Sports & Outdoors at the median; from 2 to 18 across listings), a few more on busier listings, wandering over months; now and then an attractive listing (margin after fees, velocity) draws a wave of new sellers, who sell out and leave with a half-life.

Every seller runs a repricer. Alone on a listing the buy box sits a little above the product's reference price. Each seller beyond the listing's usual crowd (busier listings carry more sellers before it is a glut) pushes the price towards a floor below the wholesale cost: the more sellers, the more aggressive the pricing — and the smaller everyone's share. The repricers follow gradually, faster down than up, and the buy box is sticky: in about half the sessions it does not move at all. The listing's price level also wanders on its own (the brand's price moves, sellers out of stock), and now and then a promotion cuts it 8–30 % for a session or two. So a crowded listing's price sinks — below cost in a glut — and recovers as the sellers leave. A phasing-out product never recovers: its reference price itself falls.

Your share of a listing's units is one rotating share against the competing sellers (1 / (nsellers + 1) on average: your repricer has average-market efficiency), with some luck from session to session. Every account is one more seller against the simulated competition — accounts never compete with each other.

Lots, stock and cash

A paid line fills at the session close as a lot with its own lead time: 2 sessions typically, sometimes 3 or 4, rarely 5 (62 / 24 / 11 / 3 %), drawn per line and revealed when the lot arrives.

• Outstanding — bought and paid, in transit: it sells nothing and pays no storage. You know the window it arrives in (arrives_window), not the session.
• On hand — it joins the account's stock of the SKU. The stock sells the account's share of the buy box at the buy box price, first in, first out across the account's lots (the oldest lot sells first; a new lot sells what the older ones leave), pays the referral and fulfilment fees on every sale (marketplace_fee in the ledger) and storage per unit on hand and session (by size tier, plus the cost of the money tied up: holding_fee).
• A lot is held at most 16 sessions from its purchase. What it has not sold by then is removed: it is not converted to cash (written off); its whole units come back to the account holder as owned goods, as on every market.

The order debit is the units at unit_cost plus an inbound fee per unit (shipping and prep). A lot's result — revenue - fees - storage - cost basis - write-off — is fixed when it fills (the market's own future and the account's earlier lots of the SKU decide it) and is exactly what its trade on record shows.

Where to see it:

• GET /api/v1/stock — per SKU: qty_on_hand, qty_outstanding, their cost, what the lots sold, the fees and storage paid, the listing now (buy box, sellers, published rank) and every lot with its stage, lead time (once arrived), arrival window (while outstanding) and expiry; totals per market. The console's Stock page shows the same.
• Trade-cart lines (GET /api/v1/cart, /cart) carry the stock of their SKU on the account they are ordered on: what is on hand and outstanding already, before you buy more.
• Positions carry stage (inbound = outstanding, on_hand, settled), qty_outstanding, qty_on_hand, fees, and lead_time once arrived. The record's trades carry sku, arrived, lead_time (once arrived) and fees_so_far; the labelled dataset has sku and lead_time columns, the menu dataset sku and category.
• GET /api/v1/markets/{id} has stock: true and rules — the market's public rules: lead-time distribution, categories (their listings and the products ranked in them), fees, the rank gate, the horizon.

Configuration

Every mechanism is configurable: XGM_WHOLESALE_CONFIG=/path/to/wholesale.json overrides any field of xgames/wholesale/config.py (lists stand for tuples). For example:

{
  "categories": [{"code": "GRO", "name": "Grocery & Gourmet Food", "slots": 300, "referral_rate": 0.12},
                 {"code": "PET", "name": "Pet Supplies", "slots": 80, "sellers": 5.4, "season_amp": 0.05}],
  "catalogue_path": "",
  "lead_time_weights": [[2, 0.62], [3, 0.24], [4, 0.11], [5, 0.03]],
  "rank_delay_tiers": [[10.0, 0], [0.0, 1]],
  "crowd_floor_vs_cost": 0.8,
  "repricer_efficiency": 1.0,
  "horizon_ticks": 16
}

A category is code, name, slots (its listings), referral_rate and its calibration: velocity (units a session at the quantile levels velocity_levels: 5 %, 10 %, 25 %, 50 %, 75 %, 90 %, 95 %, 99 %), ranks (the rank a listing selling each of those is at), rank_size (products ranked in the category), sellers (its typical crowd), cost_ratio (wholesale cost / buy box: p10, p50, p90) and season_amp, season_peak (its yearly cycle and when it peaks, as a share of the year). A category without its own calibration takes the whole assortment's.

The configuration is part of the market's frozen identity: a database records the engine and configuration its history was generated with, so switching to the wholesale engine, or changing its configuration or catalogue, needs a fresh XGM_DB_PATH.

xgames wholesale report [--config wholesale.json] prints what a configuration produces — the sales mix, the ranks, the crowds, how often prices sit below cost, the share of listings phasing out, the menu, the desk, lead times and rank delays — from the hidden state, for the operator to tune by (none of it is served).

Calibration: series that look like a real marketplace's

The market is calibrated on a real wholesale seller's FMCG assortment — in aggregate only: no listing takes a real product's sales. The sales distributions per category come from the assortment's ~150,000 SKUs; the dynamics from weekly Keepa series of ~5,900 of its listings over three years — the sales rank, the number of sellers and the buy box — measured by xgames.wholesale.calibration.panel_stats and kept as targets (xgames/wholesale/data/targets.json). xgames wholesale calibrate measures the market's own public series the same way — the session's rank as a tracker averages it, a product per listing, as a tracker follows ASINs — and prints both side by side:

The market's sellers are whole counts (a tracker's weekly averages are not), so their small moves differ. The lead times follow the design brief (2 / 3 / 4 / 5 sessions) rather than real suppliers', which run longer (a median of about three weeks, 90 % within six): lead_time_weights is the knob.

The catalogue: real SKUs, scrambled identifiers

The built-in catalogue (xgames/wholesale/data/catalogue.json.gz) was made from a seller's export with

xgames wholesale catalogue skus.tsv --out xgames/wholesale/data/catalogue.json.gz --category-map categories.json

which keeps titles, brands, product types, reference prices, size tiers, case packs and pack counts, scrambles every identifier (--scramble-key or XGM_SCRAMBLE_KEY: the same export and key give the same identifiers, another key other ones) and never keeps sales or sellers; wholesale costs are dropped unless --keep-costs (a distributor's prices are usually confidential, and the menus show every deal's cost). Recognised columns: category, type, title, brand, price (or retail_price), case_pack (or units_per_carton), size_tier (any spelling), asin (or seller_sku), parent_asin, msku, fnsku, upc, vendor_sku, part_number, number_of_items. A catalogue of your own goes in catalogue_path (--config-out writes a configuration sized to it); keep private exports out of the repository (local/ is ignored).

Mapping to a purchasing model's inputs

Determinism

Every series is generated for all listings at once in blocks of 128 sessions and is a pure function of the seed and the block: a block starts from truncated sums over the sessions before it (the demand, burst, seller, price-level and cost walks, the sales score, the seller waves) or re-runs a warm-up (the buy box price and its promotions), so any session is regenerated on its own, in any order, and the history is the same whenever it is recorded. A fresh history takes a few minutes to load in the background (a few seconds per 128 sessions per market).