# Entitlement

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

> An Entitlement is what a Customer gets from an accepted Offer: a Verb on a Noun in its Tenant, optionally bounded by a Limit.

An Entitlement is what a [Customer](/business/nouns/customer) gets from an accepted [Offer](/business/nouns/offer): a [Verb](/business/nouns/verb) on a [Noun](/business/nouns/noun) in its [Tenant](/business/nouns/tenant), optionally bounded by a [Limit](/business/nouns/limit).

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `verb` | [Verb](/business/nouns/verb) | Yes | The Verb it grants. |
| `limit` | [Limit](/business/nouns/limit) | No | The Limit that bounds it. |
| `kind` | `string` | No | Computed, never set: `feature`, or `limit` when a Limit bounds it. |

## Object
```json
{
  "$id": "https://api.sb/patentpad.com/entitlements/entitlement_1",
  "$type": "Entitlement",
  "verb": "verb_1",
  "limit": "limit_1",
  "kind": "feature"
}
```

## Relationships
- <a id="rel-granted-by"></a>An Entitlement **is granted by** one [Offer](/business/nouns/offer): an accepted [Offer](/business/nouns/offer) grants Entitlements, each a [Verb](/business/nouns/verb) on a [Noun](/business/nouns/noun), optionally bounded by a [Limit](/business/nouns/limit). `grantedBy`, inverse [`grants`](/business/nouns/offer#rel-grants).
- <a id="rel-held-by"></a>An Entitlement **is held by** one [Customer](/business/nouns/customer): a [Customer](/business/nouns/customer)’s Entitlements are what it may do right now, granted by the [Offers](/business/nouns/offer) it accepted. `heldBy`, inverse [`holds`](/business/nouns/customer#rel-holds).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Entitlement.check](/business/nouns/entitlement/check) | Check says whether a Customer may call a Verb now, how much of its Limit remains, when that resets, and which Offer lifts it. | [Agent](/business/nouns/agent) | [`Entitlement.checked`](/business/events/Entitlement.checked) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Entitlement.create](/business/nouns/entitlement/create) | Creates an Entitlement. Inherited from [Noun](/business/nouns/noun). | None. | `Entitlement.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Entitlement.get](/business/nouns/entitlement/get) | Returns one Entitlement by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Entitlement.list](/business/nouns/entitlement/list) | Returns Entitlements, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Entitlement.update](/business/nouns/entitlement/update) | Changes the given properties of an Entitlement. Inherited from [Noun](/business/nouns/noun). | None. | `Entitlement.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Entitlement.delete](/business/nouns/entitlement/delete) | Deletes an Entitlement; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Entitlement.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` |
| --- | --- | --- | --- | --- |
| `Entitlement.create` | Yes | Yes | Yes | No |
| `Entitlement.get` | Yes | Yes | Yes | Yes |
| `Entitlement.list` | Yes | Yes | Yes | Yes |
| `Entitlement.update` | Yes | Yes | Yes | No |
| `Entitlement.delete` | Yes | Yes | Yes | No |
| `Entitlement.check` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Check the latest entitlement with a customer and a verb.
```

**API**

```bash
curl -X POST https://api.sb/ledgerlark.com/entitlements/check \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer":"customer_1","verb":"verb_1"}'
```

```json
{
  "api": "https://api.sb/ledgerlark.com",
  "allowed": true,
  "entitlement": {
    "$id": "https://api.sb/ledgerlark.com/entitlements/entitlement_1",
    "$type": "Entitlement",
    "verb": "verb_1"
  },
  "remaining": 1,
  "resetsAt": "2026-10-22T12:00:00Z",
  "upgrade": {
    "$id": "https://api.sb/ledgerlark.com/offers/offer_1",
    "$type": "Offer",
    "price": {
      "amount": 400,
      "currency": "USD"
    }
  },
  "action": {
    "$id": "https://api.sb/ledgerlark.com/actions/action_1",
    "operation": "Entitlement.check",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/ledgerlark.com/actions/action_1"
  }
}
```

**SDK**

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

const { allowed, entitlement, remaining, resetsAt, upgrade } = await $.Entitlement.check({ customer: 'customer_1', verb: 'verb_1' })
```

**CLI**

```bash
npx startup-builder do Entitlement.check --json '{"customer":"customer_1","verb":"verb_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Entitlement.check({ customer: 'customer_1', verb: 'verb_1' })"
  }
}
```

## Example
A dental office on the $99 plan holds an Entitlement to send appointment reminders from its [Tenant](/business/nouns/tenant). A [Limit](/business/nouns/limit) bounds it at 1,000 reminders a month.