# Change

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

> A Change is a proposed set of writes to definitions, previewed on its own branch, checked, approved, and merged as one unit.

A Change is a proposed set of writes to definitions, previewed on its own branch, checked, approved, and merged as one unit.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | Yes | One of `Open`, `Reviewing`, `Merged`, or `Closed`. |
| `base` | [Version](/business/nouns/version) | Yes | The Version it was drafted against. |
| `tier` | `integer` | No | Launch tier from the merged diff: 3 fixes, 2 adds a Verb or Entitlement, 1 adds a Product or Offer. |

## Object
```json
{
  "$id": "https://api.sb/petpantry.shop/changes/change_1",
  "$type": "Change",
  "status": "Open",
  "base": "version_1",
  "tier": 1
}
```

## Relationships
- <a id="rel-implements-decision"></a>A Change **implements decision** one [Decision](/business/nouns/decision): every merged Change traces back to the [Decision](/business/nouns/decision) that authorized it. `implementsDecision`, inverse [`changes`](/business/nouns/decision#rel-changes).
- <a id="rel-resolves"></a>A Change **resolves** many [Issues](/business/nouns/issue): a Change names the [Issues](/business/nouns/issue) it fixes; each resolves when the last open Change naming it reaches all traffic. `resolves`, inverse [`resolvedBy`](/business/nouns/issue#rel-resolved-by).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Change.merge](/business/nouns/change/merge) | Merge applies a Change to live data with a three-way, field-level merge against its base Version. | [Engineering Lead](/agents/engineering/engineering-lead) | [`Change.merged`](/business/events/Change.merged) | None. |
| [Change.revert](/business/nouns/change/revert) | Revert undoes a merged Change with a new Change and a superseding Decision, deleting nothing. | [Engineering Lead](/agents/engineering/engineering-lead) | [`Change.reverted`](/business/events/Change.reverted) | None. |
| [Change.review](/business/nouns/change/review) | Review runs every Evaluator on a Change’s preview and records each verdict on the Change. | [Quality Lead](/agents/quality/quality-lead) | [`Change.reviewed`](/business/events/Change.reviewed) | None. |
| <a id="create"></a>[Change.create](/business/nouns/change/create) | Creates a Change. Inherited from [Noun](/business/nouns/noun). | None. | `Change.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Change.get](/business/nouns/change/get) | Returns one Change by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Change.list](/business/nouns/change/list) | Returns Changes, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

A Change is kept forever and never edited: it has no `update` or `delete`.

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

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Change.create` | Yes | Yes | Yes | No |
| `Change.get` | Yes | Yes | Yes | Yes |
| `Change.list` | Yes | Yes | Yes | Yes |
| `Change.merge` | Yes | Yes | Yes | No |
| `Change.revert` | Yes | Yes | Yes | No |
| `Change.review` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Review the latest change.
```

**API**

```bash
curl -X POST https://api.sb/petpantry.shop/changes/change_1/review \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/petpantry.shop",
  "change": {
    "$id": "https://api.sb/petpantry.shop/changes/change_1",
    "$type": "Change",
    "status": "Open",
    "base": "version_1"
  },
  "action": {
    "$id": "https://api.sb/petpantry.shop/actions/action_1",
    "operation": "Change.review",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/petpantry.shop/actions/action_1"
  }
}
```

**SDK**

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

const change = await $.Change.review({ change: 'change_1' })
```

**CLI**

```bash
npx startup-builder do Change.review --json '{"change":"change_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Change.review({ change: 'change_1' })"
  }
}
```

## Example
A Change adds a `languages` field to the [Supplier](/business/nouns/supplier) [Noun](/business/nouns/noun) of a translation marketplace. It previews on its own branch, passes its checks, and merges with one [Approval](/business/nouns/approval).