---
title: "Supply, booking and fulfilment"
url: /work/supply
---

# Supply, booking and fulfilment

> Who does the job and when: suppliers verified and matched by track record, time booked under a published rule, and orders filled, shipped and returned.

Supply, booking and fulfilment is the market side of [Work](/work.md): 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.

**Supply, booking and fulfilment: one loop.**

- A verified supplier opens capacity, and capacity offers a match.
- A match books a slot (`held`, `confirmed`, then `attended`, or `missed` with a fee) or routes an order (`claimed`, `filled`, `accepted`).
- Every outcome writes the track record, and the track record ranks the next match.

## Capability families
One family serves a [Service API](/patterns/service-api.md)'s paralegals, a [Marketplace](/patterns/marketplace.md)'s suppliers, and a [Headless SaaS](/patterns/headless-saas.md) Customer's own staff booking its clients. 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](/interfaces.md#found-and-chosen) 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
A Noun marked `supplier`, with `verify` and `payout`, gets sign-up, verification, tax forms and payout onboarding on Stripe. `capacity` sits on the supplier, `match` and `claimWithin` on the creating move, and a `slot` on a booking. The Offer carries `noShow` and `cancelBefore`, and items and orders carry `stock` and `ship`.

Deploy refuses a fee above its price, and a slot no supplier can staff. The track record, supplier orgs, staged disclosure, service-level clocks and the evidence behind every match and fee need nothing declared.

### 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.

```ts title="definition.ts"
import { define } from 'apis.dev'

/** Company research from verified researchers, ordered in one call, with a call booked when you want to talk it through. */
export default define({
  name: 'research', domain: 'research.apis.dev',
  Researcher: {
    supplier: { verify: ['identity', 'tax'], payout: 'stripe' },
    capacity: { orders: 5, hours: 'Mon-Fri 09:00-17:00', calendar: 'own' },  // what they can take on
    name: 'string', lookups: '<-Lookup.researcher',
  },
  Lookup: {                                              // one item in a supplier's catalog
    researcher: '->Researcher.lookups', orders: '<-Order.lookup',
    title: 'string', days: 'number', price: 'decimal(8,2)',
    status: { publish: [], pause: 'published', resume: 'paused' },
  },
  Order: {
    lookup: '->Lookup.orders', company: 'url', answer: 'string?', briefings: '<-Briefing.order',
    status: {
      place: { match: ['capacity', 'rating', 'price'], claimWithin: '4h' },
      claim: { in: 'placed', role: 'researcher' }, fill: { in: 'claimed', role: 'researcher' },
      accept: 'filled', contest: 'filled',
    },
  },
  Briefing: {                                            // a booking: time with a supplier
    order: '->Order.briefings', at: 'date',
    status: {
      hold: { slot: { with: 'order.researcher', minutes: 30, hold: '15m' } },
      confirm: 'held', attend: 'confirmed', miss: 'confirmed', cancel: ['held', 'confirmed'],
    },
  },
  offer: {
    'Lookup.publish': 0, 'Lookup.pause': 0, 'Lookup.resume': 0,
    'Order.place': { price: 'lookup.price', bounds: [10, 500], when: 'accepted',
                     accept: 'customer', acceptWithin: '5d', remedy: 'refund' },
    'Briefing.confirm': { price: 60, when: 'attended', noShow: 15, cancelBefore: '24h' },
    take: 0.15,                                          // your share, split on Stripe
  },
})
```

A buyer's agent holds the first free slot, under the rule the reply carries.

```http title="Response"
HTTP/1.1 201 Created
Location: /briefings/brf_1
X-Cost: price=0, currency="USD"
X-Request-Id: req_3e8a1c0f72b94d65a1e7

{
  "id": "brf_1",
  "order": "order_1",
  "with": "researcher_3",
  "at": "2026-10-30T15:00:00Z",
  "minutes": 30,
  "status": "held",
  "heldUntil": "2026-10-27T09:15:00Z",
  "rule": { "price": 60, "noShow": 15, "cancelBefore": "2026-10-29T15:00:00Z" },
  "createdAt": "2026-10-27T09:00:00Z",
  "updatedAt": "2026-10-27T09:00:00Z"
}
```

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
- **Definition and compile** checks `supplier`, `capacity`, `slot`, `match` and the no-show rule at deploy.
- **Identity, access and policy** gives two account kinds, supplier orgs with members and Roles, and mandates for suppliers' agents.
- **Model and records** keeps items, bookings, orders, stock and ratings, and rebuilds the track record from them.
- **Data and Sources** connects each supplier's catalog and calendar as an [Integration](/patterns/headless-saas.md#integrations), and a carrier's tracking. Supplier changes write back to their systems.
- **Runtime** runs the hold, claim and service-level clocks on business calendars, sends reminders as effects, and emits every move as an Event.
- **Commerce** holds funds, charges on attendance or acceptance, takes no-show fees, splits, pays out, refunds and claws back.
- **Interfaces and distribution** shows free times on the site and the portal, sends reminders in the booking's [conversation](/interfaces/channels.md), and renders the supplier's delivery screen.
- **Trust and operations** verifies suppliers and watches for fraud on both sides.

## 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 before a buyer books.
- **Free times as data.** `GET /briefings/slots?order=order_1` lists open times in the buyer's timezone, and holding and confirming are one call each.
- **An agent books under its mandate.** It holds, confirms within its budget and cancels before the cut-off; 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.
- **One record, either side.** The buyer sees its booking and order, the supplier its jobs, track record and payouts, and neither sees the other's books.

---

Every supplier, slot and order is a record with a clock, so the promise holds whoever fills it.