---
title: "Engagements"
url: /work/engagements
---

# Engagements

> Work sold over time: a scope, deliverables reviewed in rounds, change orders, requests to the client that pause the clocks, and six price models.

An engagement is work sold over time: a scope, deliverables accepted one by one, a schedule, and a price model, from proposal to close.

**An engagement from proposal to close.** A client's request.

1. Proposed: scope and price. Or declined: no charge.
2. Accepted (the client): an agreement.
3. Waiting (a request): on the client. Or clocks paused: until answered.
4. Deliverables (items in): in review rounds. Or change order: re-quoted.
5. Closed (accepted): the last accepted.

Each deliverable is accepted on its own, and a change re-quotes before it runs.

## What an engagement holds
An engagement is a [case](/work.md#families) that runs for weeks or years. Every family of [Work](/work.md) applies inside it, and these are its own.

| Family | What it does |
| --- | --- |
| Scope | What the work covers and excludes, in words the client accepts, versioned with every change order |
| Proposal and acceptance | A quote with the scope, the schedule and the price, accepted by click, signature or an agent in the call, as [an agreement](/commerce/agreements.md) |
| Deliverables | Each a Thing of its own: versioned with every upload, reviewed by the client in rounds, and accepted, rejected or remedied on its own |
| Change orders | A move that re-quotes the work left; the new price waits on the client, and the scope's history keeps both |
| Schedule and forecasts | A due date per deliverable, and a forecast date from how long the same steps took before, with how sure it is |
| Requests to the client | Items the work needs, with a due date and reminders; the case's clocks and service levels pause while the client owes them |
| Document intake | Files the client sends are read into typed fields, each stamped Inferred and checked by the step's review before the work uses it |
| Time capture | Time logged against each task by the people who did it, approved, and billed against a retainer or an hourly cap |
| Recurring service | An engagement that renews each period, such as a monthly close, with each period's deliverables made from one template |
| Close-out | The last invoice, a handoff packet to the client, and every record kept under its retention and legal hold |

| How it is priced | Charged when | Grade it may sell |
| --- | --- | --- |
| Fixed | Once, on acceptance of the whole | Up to `confirmed` |
| Milestones | As the engagement enters each state the Offer names | Up to `measured`, each milestone on its own acceptance |
| Retainer | Each month, with the hours it includes and an hourly rate past them | Up to `graded` |
| Capped time and materials | Hours captured and approved, up to the `cap` | Up to `graded` |
| Contingency | A share of an amount the record holds, such as a sum recovered | `confirmed`, from an outside party's record |
| Recurring service | Each period, on acceptance of its deliverables | Up to `measured` |

The [assurance grade](/work.md#families) rule holds: a price model never sells a grade its checks do not earn, and the publish is refused with `grade_unearned`.

### Example
The filings product sells a year of filings by milestones. Starting asks the client for two documents, and the clocks wait for them.

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

/** A year of annual reports for each client, filed by people under a licensed supervisor. */
export default define({
  name: 'filings', domain: 'filings.apis.dev',
  Engagement: {
    client: 'string', scope: 'markdown', reports: '<-Report.engagement',
    stage: {
      propose: [], accept: 'proposed',
      start: { in: 'accepted', ask: { items: ['articles', 'agent address'], within: '7d', pause: true } },
      change: { in: 'started', requote: true },        // a change order, re-quoted
      close: ['started', 'changed'],
    },
  },
  Report: {
    engagement: '->Engagement.reports', form: 'file?',
    status: { draft: [], review: 'drafted', revise: 'reviewed', approve: ['reviewed', 'revised'] },
  },
  offer: {
    'Engagement.propose': { milestones: { started: 500, closed: 1500 }, accept: 'customer', remedy: 'redo' },
    'Report.draft': 0, 'Report.review': 0, 'Report.revise': 0, 'Report.approve': 0,
  },
})
```

The client's agent reads the engagement while the work waits on it.

```http title="Response"
HTTP/1.1 200 OK
Content-Type: application/json
X-Cost: price=0, currency="USD"
X-Request-Id: req_3d8e1f60a2c74b95e7a1

{
  "id": "engagement_1",
  "stage": "started",
  "waiting": "customer",
  "ask": {
    "items": [
      { "name": "articles", "received": true },
      { "name": "agent address", "received": false }
    ],
    "due": "2026-11-03T00:00:00Z",
    "clocks": "paused"
  },
  "reports": ["report_1", "report_2"],
  "forecast": "2026-11-14"
}
```

## Engagements, deliverables and requests, state by state
Every move is a Verb the client, its agent or your team makes, and each writes its Event.

| Thing | States | What moves it |
| --- | --- | --- |
| An engagement | `proposed`, `accepted`, `started`, `changed`, then `closed`; or `declined`, `cancelled`; waiting on the customer while a request is open | The client's acceptance, the moves the file declares, a cancel under the agreement's terms |
| A deliverable | `drafting`, `in_review`, `revising`, then `accepted` or `rejected` and `remedied` | The step that drafts it, the client's review rounds, and the remedy the Offer names |
| A change order | `proposed`, then `accepted` or `declined` | Your team or the client proposes; the client accepts the new price, and nothing it adds runs before |
| A request to the client | `sent`, `partial`, then `received`, `overdue` or `waived` | Each item the client sends; reminders by its channels; your team waives an item |
| A time entry | `logged`, `approved`, then `billed` or `written_off` | The person who did the work, a reviewer, the next invoice |
| A period of recurring service | `open`, `delivered`, `accepted`, `invoiced` | The period's template, its deliverables and the client's acceptance |

## What clients, your team and agents meet
- **A client.** One place for the scope, the schedule, each deliverable's versions and every request it owes, with a date it can trust.
- **The client's agent.** It accepts a proposal, sends documents, reviews a deliverable and approves a change order, all by Verb.
- **Your team.** Requests that chase themselves, clocks that stop while the client is late, and a forecast built from your own history.
- **Finance on both sides.** Each charge tied to an accepted deliverable, a milestone or approved hours, on a signed receipt.

---

An engagement sells work over time on the same Verbs as one order, so each deliverable, change and charge is accepted on its own.