# Renewal

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

> A Renewal is the Deal for a term Subscription’s next term, opened before the term ends and closed renewed, expanded, contracted, or churned.

A Renewal is the [Deal](/business/nouns/deal) for a term [Subscription](/business/nouns/subscription)’s next term, opened before the term ends and closed renewed, expanded, contracted, or churned.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `termEndsAt` | `datetime` | Yes | When the current term ends, read from the Subscription. |
| `openedAt` | `datetime` | Yes | When it opened: by default 90 days before the term ends. |
| `usageReview` | `text` | No | Usage against each Entitlement over the term, written before any Quote. |
| `noticeSentAt` | `datetime` | No | When the renewal notice the legal floor requires went out, with the date, Price and cancel link. |
| `saveOffer` | `text` | No | The one save offer shown on cancel; it never blocks the cancel. |
| `outcome` | `string` | No | One of `renewed`, `expanded`, `contracted`, or `churned`, computed from the Subscription’s Events at the term end. |

<details>
<summary>Inherited from [Deal](/business/nouns/deal): 6 properties</summary>

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `string` | Yes | One of `Open`, `Qualified`, `Proposed`, `Won`, or `Lost`. |
| `value` | `money` | No | What the Deal is worth if won. |
| `owner` | [Worker](/business/nouns/worker) | No | The Worker who runs it. |
| `closesOn` | `date` | No | The date the buyer expects to decide. |
| `statusSince` | `datetime` | No | When it entered its current status, computed from its Events. |
| `nextStep` | `text` | No | The next dated step agreed with the buyer. |

</details>

## Object
```json
{
  "$id": "https://api.sb/tutorloop.com/renewals/renewal_1",
  "$type": "Renewal",
  "status": "Open",
  "value": {
    "amount": 60,
    "currency": "USD"
  },
  "owner": "worker_1",
  "closesOn": "2026-10-22",
  "statusSince": "2026-10-22T12:00:00Z",
  "nextStep": "Example next step",
  "termEndsAt": "2026-10-22T12:00:00Z",
  "openedAt": "2026-10-22T12:00:00Z",
  "usageReview": "Example usage review",
  "noticeSentAt": "2026-10-22T12:00:00Z",
  "saveOffer": "Example save offer",
  "outcome": "renewed"
}
```

## Relationships
- <a id="rel-renews"></a>A Renewal **renews** one [Subscription](/business/nouns/subscription): each Renewal decides one term of one [Subscription](/business/nouns/subscription); a Subscription has one Renewal per term. `renews`, inverse [`renewals`](/business/nouns/subscription#rel-renewals).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Renewal.open](/business/nouns/renewal/open) | Open starts the Renewal for a term Subscription before its term ends, with a usage review and any notice the legal floor requires. | [Success Manager](/agents/customer/success-manager) | [`Renewal.opened`](/business/events/Renewal.opened) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Renewal.create](/business/nouns/renewal/create) | Creates a Renewal. Inherited from [Noun](/business/nouns/noun). | None. | `Renewal.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Renewal.get](/business/nouns/renewal/get) | Returns one Renewal by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Renewal.list](/business/nouns/renewal/list) | Returns Renewals, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Renewal.update](/business/nouns/renewal/update) | Changes the given properties of a Renewal. Inherited from [Noun](/business/nouns/noun). | None. | `Renewal.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Renewal.delete](/business/nouns/renewal/delete) | Deletes a Renewal; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Renewal.deleted` | One-way: `send`, `do` |

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

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Renewal.create` | Yes | Yes | Yes | No |
| `Renewal.get` | Yes | Yes | Yes | Yes |
| `Renewal.list` | Yes | Yes | Yes | Yes |
| `Renewal.update` | Yes | Yes | Yes | No |
| `Renewal.delete` | Yes | Yes | Yes | No |
| `Renewal.open` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Open the latest renewal with a subscription.
```

**API**

```bash
curl -X POST https://api.sb/tutorloop.com/renewals/open \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscription":"subscription_1"}'
```

```json
{
  "api": "https://api.sb/tutorloop.com",
  "renewal": {
    "$id": "https://api.sb/tutorloop.com/renewals/renewal_1",
    "$type": "Renewal",
    "status": "Open",
    "termEndsAt": "2026-10-22T12:00:00Z",
    "openedAt": "2026-10-22T12:00:00Z"
  },
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_1",
    "operation": "Renewal.open",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/tutorloop.com/actions/action_1"
  }
}
```

**SDK**

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

const renewal = await $.Renewal.open({ subscription: 'subscription_1' })
```

**CLI**

```bash
npx startup-builder do Renewal.open --json '{"subscription":"subscription_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Renewal.open({ subscription: 'subscription_1' })"
  }
}
```

## Example
A 12-seat litigation team's Renewal opens 90 days before its term ends, and the usage review shows 9 seats active. The [Success Manager](/agents/customer/success-manager) sends a 10-seat [Quote](/business/nouns/quote), the team accepts it, and the Renewal closes `contracted`.