TBBN.Merchant Platform docs
Businessdocs/business/glossary.md

Glossary

Merchant — a business (marketplace, ecommerce platform, thrift/consignment business, classifieds site, social-commerce app) that integrates TBBN. Merchants currently own payments, taxes, fulfillment, and their seller relationships. (Stated as "currently," not "always" — founder-directed language change, conflict-resolution-log.md item 17.)

Seller — an individual who lists and trades items; also called a Marketplace profile. Every registered user gets exactly one, created together with their User at direct self-registration (Phase 22 — see conflict-resolution-log.md item 18, which reverses this entry's earlier "never signs up directly" rule). A Seller may separately be linked to one or more merchants via merchant-fed listings — see "Identity federation" below, which now describes attribution to an existing account, not identity creation.

Listing — an item a seller has listed for trade. TBBN never originates listing content; merchants create and sync listings via API. A listing's originalPrice is always merchant-supplied and is never set or discounted by TBBN.

Wants — a structured array on a listing ({category, subcategory, brand}) describing what the seller would accept in trade. Turns TBBN from a search engine into a matching engine.

Offer — a proposal from one seller (offering one or more of their own listings) to trade for one or more of another seller's listings.

Trade Session — the stateful record that exists once an offer is accepted; tracks both sides' sellers, listings, reservations, and payments through to completion. See docs/architecture/trade-session-state-machine.md.

Initiator / Requester — flow-only labels used in design and documentation to describe who listed first (initiator) vs. who made the offer (requester). These are never stored as a database role. In practice every seller who lists an item is automatically an initiator for that listing, and becomes a requester the moment they make an offer on someone else's listing — the same seller is an initiator on one listing and a requester on another simultaneously. Trade sessions store symmetric sellerA / sellerB (see db-erd.md); the only place "A" vs "B" is assigned a deterministic meaning is the storage convention documented in conflict-resolution-log.md item 2 (offer target → A, offer proposer → B) — that convention governs which column a seller lands in, not which order they act in. Do not build any workflow logic that requires trade to go in one direction — either side may act first, and once an offer is accepted, both sides may check out immediately and independently. This corrects a common misreading of the flow (see trade-session-state-machine.md's "parallel checkout" callout).

Identity federation — the process by which one human, verified separately by two or more merchants, is recognized as a single seller across those merchants. As of Phase 22 (see conflict-resolution-log.md item 18), a seller most commonly already has a Marketplace profile from direct self-registration; a merchant sends {name, verified email, verified phone} after they verify the seller, and this either matches that existing account or — if TBBN has never seen this person before — creates one on the spot (the original, still-supported path). name is a name, nickname, or username — whichever the merchant is legally able to share, never assumed to be a legal name; TBBN does not require or verify legal identity, and requests nothing beyond these three fields (see conflict-resolution-log.md item 15). If that email or phone already matches a different merchant's link, TBBN confirms it's the same human via sequential OTP (email first, then phone — both required) before attributing that merchant's seller-ref to the account. A seller with 2+ linked merchant accounts is labeled "federated" for display purposes (e.g. the merchant dashboard's Sellers page) — this is a derived fact, not a gate on whether they can log in; every seller can already authenticate directly into TBBN Exchange from registration.

Global vs. Private vs. Both vs. Enterprise (listing visibility) —

  • PRIVATE: visible only within the originating merchant's own platform.
  • GLOBAL: visible on TBBN Exchange and to all other Global-tier-or-above merchants.
  • BOTH: merchant-configurable; the merchant decides per-listing or as a platform default.
  • ENTERPRISE: visible only to the merchant's explicitly-selected enterprise trading merchants — not globally visible, not just internal.

Trade Value — OriginalPrice + RequestedAmount − WillingToPay. See docs/architecture/matching-algorithm-spec.md for worked examples.

Checkout orchestration — TBBN reserving items and redirecting each seller to the other seller's merchant checkout with the trade amount; TBBN does not currently process the payment itself.

Ring trade / multi-hop trade — a future (Phase 21, not built now) capability where a closed loop of 3+ sellers each get what they want without any pair directly having what the other wants (A→B→C→A). Documented as roadmap, not implemented in the current schema or services.