Core Concepts
CollectIQ is the trade engine loop. Every feature maps to a stage in the pipeline.
The Trade Engine Loop
Capture Intent
POST /buyer-requestsA buyer declares what they want: product, condition, max price. This creates a BuyerRequest — a standing order that persists until fulfilled or archived.
MatchRun
POST /matches/runThe match engine compares all active BuyerRequests against available Inventory. It evaluates product similarity, condition compatibility, price range overlap, and proximity.
MatchPack
Auto-generatedEach viable pairing becomes a MatchPack — a bundle containing the BuyerRequest, matched InventoryItem, confidence score, and suggested price. These appear in your dashboard for review.
Offer
POST /offersYou send an Offer to the buyer with a specific price for a matched item. Offers support accept, reject, counter, and withdraw actions — a full negotiation cycle.
SecureTrade
POST /tradesWhen an offer is accepted, a Trade is created. It tracks the full lifecycle: payment, shipping, delivery, completion. Optional deposit holds via Stripe.
Outcome
PATCH /trades/{id}The trade resolves to an outcome: completed, cancelled, or disputed. Each outcome feeds back into the system to improve future matching.
TradeGraph
GET /tradegraph/demandAggregated trade data feeds the TradeGraph — demand insights, sourcing recommendations, and intelligence that close the loop by informing what to stock next.
Key Entities
Workspace
A tenant — one shop/dealer. All data is workspace-scoped. Users can belong to multiple workspaces.
BuyerRequest
A declared intent to purchase. Status: new → matched → needs_contact → closing → archived.
InventoryItem
A sellable item with product name, condition, price, category, location, and metadata.
MatchPack
An engine-generated pairing of BuyerRequest + InventoryItem with a confidence score.
Offer
A price proposal on a match. Supports negotiation: pending → accepted/rejected/countered/withdrawn.
Trade
The transaction lifecycle: initiated → payment_pending → paid → shipped → delivered → completed.
Hold
A reservation intent with optional deposit. Prevents item from being sold to others.
Contact
A customer record linking a person to their requests, trades, and communication history.
Multi-Tenancy
CollectIQ is multi-tenant by design. Every API request is scoped to the authenticated workspace. Data isolation is enforced at the database level with Row-Level Security (RLS).
Users can own multiple workspaces (for multi-location dealers) and switch between them. Team members can be invited with role-based access (owner, admin, member).
Pagination
All list endpoints support offset-based pagination:
GET /api/v1/inventory?limit=25&offset=50
{
"data": [...],
"total": 142,
"limit": 25,
"offset": 50
}