Stockroom Channels and Sales Design

Part of the Simple Agility stack. Canonical copy: ~/source/stockroom/docs/superpowers/specs/2026-10-08-stockroom-channels-and-sales-design.md. This page mirrors it for retrieval. Status: approved 2026-10-08; built as phases 5 (plan) and 6 (plan), reviewed 2026-10-09; not yet deployed or connected to eBay. Earlier design: StockroomIntakeInventoryPricingDesign.

Context

Stockroom (phases 1–4) takes items in, prices and routes them, prepares channel-neutral listing content, and tracks where every item physically is (crates, labels, picks, counts). It knew nothing about what happens after an item is ready. This is sub-project 2, channels and sales: where each item is listed, recording a sale, removing a sold item from the other channels within minutes, and getting sold items out the door.

What the operator decided

• Channels: FBA, eBay, Craigslist, maybe Facebook Marketplace. A sold item must leave the other channels within minutes. FBA stock is never shown on any other channel.
• Posting is assisted copy/paste on every channel (not a paid crosslister, not browser automation). Stockroom prepares title, price, plain-text description, SKU and photos and links to the posting page; the operator posts and pastes the post's link back.
• eBay is listed by hand with the Stockroom SKU in eBay's Custom label. Once connected, Stockroom finds the listing by SKU, sees eBay sales, and ends the listing when the item sells elsewhere. Posting through eBay's API may come later.
• No channel scheduling: Stockroom records wherever the operator posts.
• Alerts by Telegram, from a bot separate from jakemon's, repeated until the posts are deleted.
• Money: the price is exact; eBay fees are estimated from the triage fee rules; postage can be typed. The sale stores triage's predicted net beside the realised net (feedback loop).
• Shipping: a sale that ships goes onto a To ship pick list. FBA and buyback get end states (Sent to Amazon; a buyback batch sale).
• eBay sales are found by polling every 2 minutes; listings every 15. Outbound calls only.

Lifecycle

ready ──record a post──► listed ──sale──┬─► to_ship ──shipped──► sold   (eBay, or any sale marked "needs shipping")
  ▲   ◄──every post taken down──┘       └─► sold                       (handed over: Craigslist, Facebook, in person)
  ├── sale with no post (e.g. at a market) ──► sold / to_ship
  ├── FBA pick list closed as "Sent to Amazon" ──► at_fba
  ├── buyback batch sold ──► sold
  └── cancel sale ◄── (back to listed if a post is still up, else to the status before the sale)

• Any item still in stock can be sold; lot members are sold through their lot.
• Once an item is listed or beyond, only this subsystem changes its status; triage preferring FBA flags look closer instead.
• sold and at_fba clear the location, so counts and Find stop expecting the item.
• The FBA rule is enforced both ways: no post for an FBA-routed item; no override to FBA while a post is open.

Data

• channel_listing — one post: channel (ebay, craigslist, facebook), eBay item number or link, price, status (active, delist_pending, ended), end reason, source (manual, ebay_sync). One open post per item and channel.
• sale — channel (ebay, craigslist, facebook, in_person, buyback), status (active, cancelled, oversold), price, shipping charged, fees and postage (each marked estimated or entered), net, the predicted net, shipping state, the status before the sale, eBay order and line numbers. One active sale per item.
• sale_batch — a buyback sale split evenly across its items; correctable later.
• app_setting — the packing location and eBay sync bookmarks. ebay_unmatched (phase 6) — eBay sales or listings with no matching SKU.
• Pick lists gain the reason to_ship. New statuses listed, to_ship, sold, at_fba.

Flows

1. Posting — a Post card on the item page with a tab per channel: copy buttons, Share photos (the phone's share sheet), Open channel, and I posted it. A Ready to post queue.
2. Selling — Stock › Sell: scan the sold item (a product barcode prefers a copy with an open post), confirm channel and price, record. Other posts go to To delist; eBay posts are ended by Stockroom once eBay is connected.
3. To delist — every post waiting to be deleted, with its link and a Deleted button; the time from sale to delisting is measured.
4. Shipping — the To-ship pick list into a packing location; Shipped per sale (automatic from eBay in phase 6); the list closes itself.
5. FBA and buyback — closing an FBA list offers Sent to Amazon; closing a buyback list records the vendor sale.
6. Sales page — sales with predicted versus realised net, filters and totals; Cancel sale.

eBay connection and alerts (phase 6)

• A user refresh token (EBAY_REFRESH_TOKEN, about 18 months) from signing in once; kept in the environment, never the database.
• An EbaySellerAccount port: active listings (Trading GetMyeBaySelling), orders changed since a time (Fulfillment getOrders), end a listing (Trading EndFixedPriceItem, by item number — the only way to end a listing created on the website).
• Sync jobs on the existing runner: orders every 2 min (record, adopt a hand-recorded sale, oversold, cancelled, shipped, unmatched), listings every 15 min (record by SKU, end listings for sold items, flag FBA-routed or multi-quantity listings, unmatched).
• A Notifier port with a Telegram adapter; durable messages; reminders every 30 minutes while posts await deletion. Every eBay sale is messaged, with the posts left to delete or "No other posts to take down" (the operator's choice, 2026-10-09; the spec first messaged only a sale with posts to delete).
• No buyer data is stored. eBay's account-deletion exemption is re-checked when connecting.
• Calls to eBay are functional inputs and outputs of selling, so they belong in Stockroom; only the sync-age gauge is for jakemon (observability plane).

Telemetry

Counters for posts, sales, cancellations, delistings (by API or by hand), oversold items, sync runs and notifications; gauges stockroom_delists_pending and stockroom_ebay_sync_age_seconds; the timer stockroom_delist_seconds{channel} — the measure of "within minutes". Per the telemetry contract.

Rollout

• Phase 5, listings and sales — everything above with eBay handled by hand; no new credentials.
• Phase 6, eBay connection and alerts — needs the eBay refresh token and a Telegram bot from the operator.
• Photo-first identification follows.

Out of scope

Posting through eBay's API, crosslisters, browser automation; Poshmark; returns and refunds after shipping, buying postage; FBA sales import (the SP-API plan); exact eBay fees; channel scheduling; multi-quantity listings.

Risks

• eBay's account-deletion exemption may no longer fit once order numbers are stored (no buyer data is).
• Trading API calls with an OAuth user token are documented but unverified against the operator's keyset.
• eBay call limits are unverified (about 800 calls a day planned).
• The double-sale window cannot be closed by polling; it is detected (oversold), not prevented.
• Custom label typos land in Unmatched eBay, which notifies.

---

Cluster Hub: Stockroom Hub (stockroom)