How this fits the other docs. The foundation — the Trade Me API capability map, the AI photo→listing pipeline, and the Trade Me ↔ Shopify sync engine — is specced in trademe-ai-first-automation.md and trademe-shopify-stock-hub.md. This page is the north star those build toward: the full operating system with every channel, the fulfilment workflow, and the marketing + accounting loops wired in.
1 The single source of truth
The hub owns the stock. Every channel and every system reads from it and writes back to it — they never talk to each other.
The Stock Hub · single source of truth
1 physical unit = 1 record
IMEI/serial · grade · cost · photos · status · price
◆ Sell channels
- Shopify (own site)
- Trade Me
- Meta Shops (FB/IG)
- Google Shopping
- + eBay AU later
▸ Fulfilment
- Barcode / IMEI scan
- Docket + label print
- NZ courier + tracking
↻ Marketing loop
- Stape server-side
- Google Ads conv.
- Meta CAPI
$ Accounting
- Xero sale + COGS
- Stock valuation
- Per-unit margin
Because there's one truth, the same sale event does four jobs at once: it withdraws the listing everywhere else, triggers the dispatch, books the sale into accounting, and reports the conversion to the ad platforms. Nothing is keyed in twice; nothing drifts out of sync.
2 The system map — every API, grouped by job
What connects to the hub, what it does, and the interface it uses. Foundation pieces are buildable now; the rest is the Phase 2 build-out.
| System | Job | Interface | Stage |
|---|
| Shopify | Own-store listings, inventory, orders | Admin GraphQL API + orders/paid webhook | Foundation |
| Trade Me | List / withdraw / photos / sold-items / Q&A / feedback | Selling API (OAuth 1.0a, poll) | Foundation |
| Meta — FB/Instagram Shops | Product feed to Facebook & Instagram shopping | Commerce / Catalog API | Phase 2 |
| Google Shopping | Free listings + Shopping ads feed | Merchant Center Content API | Phase 2 |
| Barcode / IMEI scanner | Intake capture & pick confirmation | USB/Bluetooth HID → hub | Phase 2 |
| PhotoRoom | Background removal / clean product shots | PhotoRoom API (~$0.02/img) | Foundation |
| Vision LLM (Claude) | Title, attributes, description, grade from photos | Anthropic API | Foundation |
| Courier (Starshipit / GoSweetSpot) | Shipping labels + tracking numbers | Carrier API → NZ Post / NZ Couriers / Aramex | Phase 2 |
| Label / thermal printer | Auto-print order docket + shipping sticker | Print API / PDF spool | Phase 2 |
| Stape sGTM | Server-side conversion routing (the loop) | sGTM container (MCP) | Phase 2 |
| Google Ads | Conversion import for paid attribution | Ads API — offline / enhanced conversions | Phase 2 |
| Meta Conversions API | Server-side purchase events | CAPI via Stape | Phase 2 |
| Xero | Record the sale, COGS, stock valuation | Xero Accounting API | Phase 2 |
One honesty note on "Facebook Marketplace". Meta's Shops on Facebook & Instagram are fully feed-automatable via the Catalog API — that's the version we build. Peer-style Marketplace listings don't have an open public listing API (manual or approved-partner only), so treat "Meta" as Shops-via-catalog, with Marketplace as a manual add-on if it ever earns its keep.
3 Inbound — "do it once, everything goes out"
New stock arrives. One pass at the bench, and the unit is live across every channel.
01
Scan & gradeScan IMEI/serial, assign grade (A/B/C), battery health, cost, supplier, photos. Hub mints the SKU + master record.
02
AI enrichPhotoRoom cleans the shots; vision LLM writes the title (leads "Refurbished"), fills attributes, drafts the description, suggests a price.
03
Batch approveOperator reviews a grid of drafts, edits inline, ticks approve. 200 units reviewed in minutes.
04
Publish everywhereOne action → live on Shopify, Trade Me, Meta Shops & Google — each listing linked back to the one master record.
The payoff: the work that today is done by hand, per-listing, per-channel, collapses to one enrich-and-approve pass. List once; sell everywhere; and every listing is built to the CRO standard the store audit found missing (titles, attributes, photos, "Refurbished").
4 Outbound — the fulfilment workflow
The flow you described: order in → alert → find & scan → the scan triggers everything else.
An order lands — from any channelA Shopify sale (instant webhook) or a Trade Me sale (caught on the next poll) drops into one unified queue. The operator gets an alert / email.
Shopify orders/paid · Trade Me SoldItems poll
Find the unit & scan itThe operator walks to the shelf, finds the device, and scans the barcode / enters the reference. The hub checks the scanned IMEI matches the order — so the right physical unit ships.
Scan-to-confirm against the master record
The scan triggers the printThat one scan fires the order docket and the shipping label/sticker — buyer address, courier, tracking — printing together, ready to peel and stick.
Courier API (label + tracking) → thermal printer
Label on, packed, lodgedOperator sticks the label, packs, and lodges with the courier. The physical job is done.
Stock updated — withdrawn everywhereThe hub marks the unit sold and pulls the listing from every other channel (the unique-unit withdrawal — no overselling the same phone twice).
Shopify set-qty-0 / unpublish · Trade Me Withdraw
Tracking pushed backThe tracking number flows back to the channel that made the sale, and the order is marked dispatched.
Trade Me mark-shipped · Shopify fulfilment
Booked for accountingThe sale, the unit's cost (COGS) and the stock decrement post to Xero automatically — the books stay live, per-unit margin is captured.
Xero Accounting API
Conversion fired back to the ad networksThe sale event is reported server-side to Google Ads and Meta — closing the loop so the ad spend that drove the sale gets the credit (see §5).
Stape sGTM → Google Ads + Meta CAPI
One scan, eight outcomes. The operator does two physical things — find it, scan it, pack it. The system does the other six: confirm, print, ship-update, withdraw-everywhere, book it, and report the conversion. That's the leverage — a team's worth of admin compressed into a barcode beep.
The honest tension — routing vs multi-channel. The companion spec's default oversell fix is to route unique high-value units to ONE channel (TM-only or Shopify-only). That deliberately reduces the dual-listing this Hub exists to enable — so be clear-eyed about where the value actually lands: the Hub's clearest payoff is the list-once pipeline plus commodity / multi-quantity stock (accessories, parts, new-old-stock), which dual-lists safely. Dual-listing is reserved for low-oversell-risk stock; premium qty-1 units are single-channel by policy. The "list once → sell everywhere" promise holds fully for the commodity pool, and partially — by design — for the unique high-value units.
5 The marketing loop — sales back to the ad networks
The piece most inventory systems never touch — and the one squarely in your wheelhouse.
Most stores spend on ads but can only measure the sales the website pixel happens to see. With the hub as the source of truth, every sale is a known event — so we route the right signal to the right platform, server-side, through Stape:
Own-store (Shopify) sales — full closed loop
- Click ID captured on the way in (gclid / fbclid / wbraid)
- Purchase fired server-side via Stape sGTM → Google Ads + Meta CAPI
- Enhanced conversions for accuracy; deduped, durable, ad-blocker-proof
- Smarter bidding → lower CPA → more profitable scale
Marketplace (Trade Me) sales — blended & honest
- No click ID on a Trade Me sale — so we don't fake attribution
- Booked in the hub for blended ROAS & true channel P&L
- Where a click identifier exists, fed as an offline conversion
- Google Shopping / PMax fed clean stock + price from the same hub
Why it's the differentiator: this is exactly the server-side conversion plumbing you already run for Gerrard's (Stape sGTM + offline conversion import). Bolting it onto the inventory hub means the ad platforms learn from real, deduplicated, full-funnel sales data — across channels — which is how you out-bid competitors flying blind on pixel-only data.
6 Why a single source of truth changes the business
Once
Touch a unit one time — list, sell, ship, book & report all flow from it
0×
Double-keying — no re-entering stock, sales or numbers between systems
Live
Books, stock & ad data are always current, not reconciled weekly
Every sale becomes a data flywheel: it feeds the ad platforms better signal, feeds accounting a clean margin, feeds reporting a real-time picture of what's selling, and frees the listings on every other channel — automatically. The business runs on two operators + a picker not because corners are cut, but because the system does the connective work a back-office team would otherwise do by hand.
7 Where we can go — the build path
P1
FoundationMaster catalogue + AI listing publisher + Trade Me ↔ Shopify unique-unit sync. (Specced in the companion docs.)
P2
This pageScan-driven fulfilment + auto-print + courier, the ads loop (Stape → Google/Meta), Xero, Meta Shops + Google feeds.
P3
Scale channelseBay AU, Reebelo, Mighty Ape as new spokes — the hub doesn't change, you just add adapters.
★
North starNear-autonomous ops — and the option to multi-tenant it as a product for other NZ Shopify + Trade Me sellers.
It's an ambitious build — and that's the point. Foundation pays for itself on TYDI alone. Phase 2 is the goal we aim at: the moment a barcode beep runs the whole back office and every sale teaches the ad platforms, TYDI isn't "a store that uses AI" — it's an operating system that happens to sell refurbished electronics. That's the moat, and the thing worth pointing the build at.
North-star operating-model vision, not a build spec — each block becomes its own project. API availability (esp. Meta Marketplace, Google Ads offline-conversion attribution without a click ID, and Trade Me's polling-only model) should be re-verified before committing engineering time. Foundation pieces are documented and buildable today; Phase 2 is the aspirational target.
← Back to the document hub