# Order

URL: /business/nouns/order · Id: `noun:order`

> An Order is a Customer’s commitment to buy one or more Offers once, moving from placed to paid, fulfilled, and closed.

An Order is a [Customer](/business/nouns/customer)’s commitment to buy one or more [Offers](/business/nouns/offer) once, moving from placed to paid, fulfilled, and closed. A recurring purchase is a [Subscription](/business/nouns/subscription), not an Order.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `total` | `money` | Yes | The amount charged. |
| `status` | `string` | Yes | One of `placed`, `paid`, `fulfilled`, `closed`, `canceled`, or `refunded`. |
| `merchantOfRecord` | [Party](/business/nouns/party) | No | The Party that charges and books the revenue. |
| `outside` | `boolean` | No | Computed: true when its Customer shares no owner, Studio account, Agreement, or sibling chain with the Startup. |
| `lines` | `json` | No | Each Offer bought, its quantity, amount and the Party that charges for it; a Service line carries its own verdict. |
| `fulfillment` | `string` | No | Where a Service Order’s work stands between `paid` and `fulfilled`. |
| `payment` | `string` | No | `authorized` when the Quote is accepted; `captured` on the Event the Outcome Contract `earns` names. |
| `revisionsUsed` | `integer` | No | Revisions the Customer has asked for, counted against the Outcome Contract’s `revisions`. |
| `risk` | `number` | No | The payment’s fraud risk score from 0 to 99 at screening, as Stripe scored it. |
| `tax` | `money` | No | The sales tax, VAT or GST computed at placement for the buyer’s location and the Offer’s tax category. |
| `taxJurisdiction` | `string` | No | Where the tax is owed, such as `US-CA` or `EU-DE`, or `none` when no registration applies. |
| `brief` | `json` | No | The scope a Service Order bought, from its Quote request: sizes, inputs and turnaround. Intake checks the inputs against it. |
| `dueAt` | `datetime` | No | When a Service Order’s work is due; time waiting on the Customer moves it later. |
| `taxExemption` | [Credential](/business/nouns/credential) | No | The exemption or resale certificate that zeroed the tax, when one applies. |
| `collectedBy` | `string` | No | The id of the venue that charged the buyer and pays the Startup; unset when the Startup’s own checkout collected. |

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/orders/order_1",
  "$type": "Order",
  "total": {
    "amount": 39,
    "currency": "USD"
  },
  "status": "placed",
  "merchantOfRecord": "party_1",
  "outside": true,
  "lines": {},
  "fulfillment": "intake",
  "payment": "authorized",
  "revisionsUsed": 1,
  "risk": 1,
  "tax": {
    "amount": 39,
    "currency": "USD"
  },
  "taxJurisdiction": "US-CA",
  "brief": {},
  "dueAt": "2026-10-22T12:00:00Z",
  "taxExemption": "credential_1",
  "collectedBy": "aws-marketplace"
}
```

## Relationships
- <a id="rel-buys"></a>An Order **buys** many [Offers](/business/nouns/offer): an Order commits to buying one or more [Offers](/business/nouns/offer) once. `buys`, inverse [`orderedIn`](/business/nouns/offer#rel-ordered-in).
- <a id="rel-disputes"></a>An Order **has** many [Disputes](/business/nouns/dispute): the Order whose delivery or charge the [Dispute](/business/nouns/dispute) contests. `disputes`, inverse [`contests`](/business/nouns/dispute#rel-contests).
- <a id="rel-placed-by"></a>An Order **is placed by** one [Customer](/business/nouns/customer): a [Customer](/business/nouns/customer) commits to one-time purchases as Orders. `placedBy`, inverse [`places`](/business/nouns/customer#rel-places).
- <a id="rel-quote"></a>An Order **has** one [Quote](/business/nouns/quote): the Order the [Quote](/business/nouns/quote) becomes when the buyer accepts it before it expires. `quote`, inverse [`acceptedAs`](/business/nouns/quote#rel-accepted-as).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `placed` (first) | The Customer committed, with the Offer Version and price fixed; nothing is charged yet. | `paid` by [Order.pay](/business/nouns/order/pay); `canceled` by [Order.cancel](/business/nouns/order/cancel) |
| `paid` | Its amount is settled and its Entries posted; a Service Order’s work runs in `fulfillment`. | `fulfilled` by [Order.fulfill](/business/nouns/order/fulfill); `closed` by [Order.confirm](/business/nouns/order/confirm); `canceled` by [Order.cancel](/business/nouns/order/cancel); `refunded` by [Order.refund](/business/nouns/order/refund) |
| `fulfilled` | What it bought is granted: Entitlements for software and data, or a shipment for goods. | `closed` by [Order.confirm](/business/nouns/order/confirm); `refunded` by [Order.refund](/business/nouns/order/refund) |
| `closed` | The Customer signed off, which earns the Startup its fee. | `refunded` by [Order.refund](/business/nouns/order/refund) |
| `canceled` | Ended before fulfillment, with any payment returned in full. | None: it ends here. |
| `refunded` | Its payment returned in full, with the reversing Entries posted; a partial refund keeps its state. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Order.cancel](/business/nouns/order/cancel) | Cancel ends an Order before fulfillment and returns any payment in full. | [Customer](/business/nouns/customer) | [`Order.canceled`](/business/events/Order.canceled) | Two-way: `try`, `send`, `do` |
| [Order.confirm](/business/nouns/order/confirm) | Confirm records the Customer’s sign-off on delivered work, which closes the Order and earns the Startup its fee. | [Delivery Manager](/agents/operations/delivery-manager) | [`Order.confirmed`](/business/events/Order.confirmed) | One-way (money): `send`, `do` |
| [Order.deliver](/business/nouns/order/deliver) | Deliver hands the finished work of a Service Order to its Customer and opens the acceptance window. | [Delivery Manager](/agents/operations/delivery-manager) | [`Order.delivered`](/business/events/Order.delivered) | Two-way: `try`, `send`, `do` |
| [Order.dispute](/business/nouns/order/dispute) | Dispute contests a delivered Order under its Outcome Contract and starts the remedy the contract names. | [Billing Specialist](/agents/finance/billing-specialist) | [`Order.disputed`](/business/events/Order.disputed) | Two-way: `try`, `send`, `do` |
| [Order.fulfill](/business/nouns/order/fulfill) | Fulfill grants what an Order bought: Entitlements for software and data, a shipment for goods. | [Delivery Manager](/agents/operations/delivery-manager) | [`Order.fulfilled`](/business/events/Order.fulfilled) | Two-way: `try`, `send`, `do` |
| [Order.pay](/business/nouns/order/pay) | Pay settles an Order’s amount through the Startup’s payment account and posts the matching Entries. | [Billing Specialist](/agents/finance/billing-specialist) | [`Order.paid`](/business/events/Order.paid) | One-way (money): `send`, `do` |
| [Order.place](/business/nouns/order/place) | Place commits a Customer to buy an Offer once and records the Offer Version and price at that moment. | [Founder](/agents/founding/founder) | [`Order.placed`](/business/events/Order.placed) | Two-way: `try`, `send`, `do` |
| [Order.refund](/business/nouns/order/refund) | Refund returns all or part of an Order’s payment to the Customer and posts the reversing Entries. | [Billing Specialist](/agents/finance/billing-specialist) | [`Order.refunded`](/business/events/Order.refunded) | One-way (money, customer): `send`, `do` |
| [Order.revise](/business/nouns/order/revise) | Revise sends delivered lines back for one counted revision, with the changes the Customer asks for. | [Delivery Manager](/agents/operations/delivery-manager) | [`Order.revised`](/business/events/Order.revised) | Two-way: `try`, `send`, `do` |
| [Order.screen](/business/nouns/order/screen) | Screen scores an Order’s payment before it is charged and allows, authenticates, holds or blocks it by the Startup’s risk Policy. | [Risk Analyst](/agents/operations/risk-analyst) | [`Order.screened`](/business/events/Order.screened) | Two-way: `try`, `send`, `do` |
| [Order.start](/business/nouns/order/start) | Start checks a Service Order’s inputs against its brief, then moves it from intake to working and starts its deadline. | [Delivery Manager](/agents/operations/delivery-manager) | [`Order.started`](/business/events/Order.started) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Order.create](/business/nouns/order/create) | Creates an Order. Inherited from [Noun](/business/nouns/noun). | None. | `Order.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Order.get](/business/nouns/order/get) | Returns one Order by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Order.list](/business/nouns/order/list) | Returns Orders, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Order.update](/business/nouns/order/update) | Changes the given properties of an Order. Inherited from [Noun](/business/nouns/noun). | None. | `Order.updated` | Two-way: `try`, `send`, `do` |

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Order.create` | Yes | Yes | Yes | No |
| `Order.get` | Yes | Yes | Yes | Yes |
| `Order.list` | Yes | Yes | Yes | Yes |
| `Order.update` | Yes | Yes | Yes | No |
| `Order.cancel` | Yes | Yes | Yes | No |
| `Order.confirm` | Yes | No | No | No |
| `Order.deliver` | Yes | Yes | Yes | No |
| `Order.dispute` | Yes | Yes | Yes | No |
| `Order.fulfill` | Yes | Yes | Yes | No |
| `Order.pay` | Yes | No | No | No |
| `Order.place` | Yes | Yes | Yes | No |
| `Order.refund` | Yes | No | No | No |
| `Order.revise` | Yes | Yes | Yes | No |
| `Order.screen` | Yes | Yes | Yes | No |
| `Order.start` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Place the latest order with an offer.
```

**API**

```bash
curl -X POST https://api.sb/ledgerlark.com/orders/place \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer":"offer_1"}'
```

```json
{
  "api": "https://api.sb/ledgerlark.com",
  "order": {
    "$id": "https://api.sb/ledgerlark.com/orders/order_1",
    "$type": "Order",
    "total": {
      "amount": 400,
      "currency": "USD"
    },
    "status": "placed"
  },
  "action": {
    "$id": "https://api.sb/ledgerlark.com/actions/action_1",
    "operation": "Order.place",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/ledgerlark.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const order = await $.Order.place({ offer: 'offer_1' })
```

**CLI**

```bash
npx startup-builder do Order.place --json '{"offer":"offer_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Order.place({ offer: 'offer_1' })"
  }
}
```

## Example
A dropship store takes an Order for two espresso-machine filters, `total: 38.00`. It moves to `paid` at checkout, `fulfilled` when the parcel ships, and `closed` when tracking shows delivery.