Supply, booking and fulfilment
View as Markdown
Open in
Supply, booking and fulfilment is the market side of Work: who does the job, when, and how it reaches the buyer. Every visit, fill and shipment writes the track record that ranks the next match.
Filled: what the buyer or the supplier sees. Hollow: a step inside the platform.
Capability families
The same family serves your own people, such as a Service API's paralegals, and a Marketplace's suppliers. It also serves a Customer's own staff, when a Headless SaaS lets each Customer book its own clients. A supplier is an account kind, so every move below is a Verb a supplier's agent can call under a mandate.
| Family | What it gives every product |
|---|---|
| Join and verify | A supplier applies and passes the checks your verify names (identity, tax, a credential and its expiry) before it lists an item or claims a job |
| Capacity | What each supplier can take on: work in hand at once, working hours, a calendar of its own, skills and credentials. A supplier at capacity leaves matching until work closes |
| Matching | A job goes to the supplier it names, else to the best by the keys you rank (capacity, rating, price, credential). Unclaimed in its window, it is rematched, and every match records why |
| Track record | On-time rate, first-time acceptance, no-shows, contests and ratings per supplier, computed from the record and never typed. Every item shows it, and matching reads it |
| Supplier orgs | A supplier with members, Roles and agents of its own under one payout account; a job is matched to the org and claimed by a member |
| Staged disclosure | What a supplier sees of the buyer before a claim, after it and after acceptance. Contact details and records open only as the work needs them |
| Calendars and availability | Free times computed from hours, bookings, buffers and each party's timezone; a business calendar closes holidays |
| Holds and bookings | A slot held for minutes while the buyer confirms, then confirmed; a waitlist fills a cancelled slot in order |
| The no-show rule | Free cancellation up to a cut-off, then a fee, and a fee for a no-show; both print on the offer card and charge only under the published rule |
| Service-level clocks | Claim within, start within, deliver within. A lapsed clock rematches, escalates or applies the remedy the Offer names |
| Orders and fulfilment | One order lifecycle for delivered work and for goods: placed, claimed, filled, then accepted, contested or returned |
| Inventory and shipment | Stock per item and place, held at placement, committed at fulfilment, released on cancel; shipments tracked as observed Events; returns under the refund rule |
Lifecycles and states
| Thing | States | What moves it |
|---|---|---|
| A supplier | applied, verifying, verified, paused, removed | Verification passes or fails, or a credential expires; you or the supplier pause; a removal keeps the record |
| A supplier's capacity | open, full, away | Claims and closes; the supplier's hours and calendar |
| A match | offered, then claimed, declined or lapsed | The supplier's claim, or the claim clock; a decline or lapse rematches |
| A booking | held, confirmed, then attended, missed or cancelled; or released | The buyer's Verbs, the hold clock, the supplier's mark at the slot's end, and the no-show rule |
| A waitlist place | waiting, offered, then taken or lapsed | A cancelled slot, and the hold clock on the offer |
| An order | placed, claimed, filled, then accepted, contested or returned | The supplier's claim and fill, the rematch clock, and the buyer's acceptance |
| A stock hold | held, then committed or released | Placement, fulfilment, a cancel or a lapsed hold |
| A shipment | packed, shipped, delivered; or lost | The supplier, then the carrier's tracking, arriving as observed Events |
| A return | requested, approved, received, refunded; or declined | The buyer, the refund rule in the Offer, and the supplier's receipt of the goods |
Matching is a step and its result is a state. The buyer sees held and claimed; who else was offered the job, and why they were passed over, stays in the evidence.
What you declare, what the platform does
| You declare | The platform does |
|---|---|
A Noun marked supplier, with verify and payout | Runs sign-up, verification, payout onboarding on Stripe, tax forms and the supplier's side of the portal |
capacity on the supplier: work in hand, hours, a calendar | Computes free times and open capacity, and takes a full supplier out of matching |
match keys and claimWithin on the creating move | Routes each job, rematches on a lapse, and records why each match was made |
A slot on a booking: with whom, how long, the hold | Offers free times, holds and confirms, fills from the waitlist, and sends the reminders in the booking's conversation |
noShow and cancelBefore in the Offer | Prints both on the offer card and the terms, charges the fee under the rule, and refuses a deploy whose fee exceeds the price |
stock on an item and ship on an order | Holds and commits stock, refuses an oversold item with a cure, takes tracking as Events, and runs returns |
| Nothing else | The track record, supplier orgs, staged disclosure, service-level clocks, and the evidence behind every match and every fee |
Example
research adds a booked call. After an order is filled, the buyer books 30 minutes with the researcher who filled it: $60, and a $15 fee for a no-show.
import { define } from 'apis.dev'
/** Company research from verified researchers,A buyer's agent holds the first free slot. The reply carries the rule it is held under.
HTTP/1.1 201 Created
Location:Confirming holds $60 on the buyer's card and charges nothing. Attendance charges it and splits it: $51 to the researcher, $9 to you.
A missed call charges $15 under the same split, and a cancel before 15:00 the day before costs nothing. An unconfirmed hold releases at 09:15 and offers the slot to the waitlist.
Contracts with the other subsystems
| Subsystem | What this family takes from it | What it gives back |
|---|---|---|
| Definition and compile | supplier, capacity, slot, match and the no-show rule, checked at deploy: a fee above the price, or a slot no supplier can staff, is refused | The roster and its capacity, which the staffing check reads |
| Identity, access and policy | Two account kinds, supplier orgs with members and Roles, mandates for suppliers' agents | Grants for staged disclosure, opened step by step |
| Model and records | Items, bookings, orders, stock and ratings as records | The track record, as a projection rebuilt from them |
| Data and Sources | Each supplier's catalog and calendar, connected as an Integration; a carrier's tracking | Supplier changes written back to their own systems |
| Runtime | Hold, claim and service-level clocks on business calendars; reminders as effects | Briefing.missed, Order.claimed, Shipment.delivered and every other move as an Event |
| Commerce | Held funds, charge on attendance or acceptance, no-show fees, splits, payouts, refunds and clawbacks | The move that charges, and each supplier's share |
| Interfaces and distribution | Free times on the site and the portal; reminders in the booking's conversation | The supplier contracts a delivery screen renders |
| Trust and operations | Supplier verification and risk, fraud on both sides | The evidence behind every match, fee and contest |
What Customers and their agents meet
- The rule before the slot. The offer card prints the price, the no-show fee and the cut-off, so a buyer knows the cost of a miss before it books.
- Free times as data.
GET /briefings/lists open times in the buyer's timezone; holding one is one call, confirming is a second.slots? order= order_1 - An agent books under its mandate. It holds, confirms within its budget, and cancels before the cut-off when its task changes. A fee past the mandate's limit waits for its person.
- A supplier's day. A researcher, or its agent, claims orders up to capacity, fills them, marks each call attended or missed, and reads each payout.
- A fee can be disputed. A buyer disputes a no-show fee with the receipt. The join record and the supplier's mark are the evidence, and the answer is an Event.
- One record, either side. The buyer sees the booking and the order; the supplier sees its jobs, its track record and its payouts. Neither sees the other's books.
Every supplier, slot and order is a record with a clock, so the promise holds whoever fills it.
Work
Jobs done by agents and people: cases, tasks, review, licensed supervision, delivery and acceptance, each step on the cheapest worker that meets its grade.
Agents inside the product
An agent per Customer, three ways: a member of its org, a worker on its queue, and the client of record under a mandate, each through the same gate as a person.