# Entitlement routes: check

URL: /code/api/entitlement/verbs · Id: `page:code/api/entitlement/verbs`

> The Entitlement Verbs check as api.sb routes, with inputs, result, refusals and an example.

Reference for [Entitlement](/business/nouns/entitlement), one group of [Entitlement routes](/code/api/entitlement).

### 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. [Verb page](/business/nouns/entitlement/check?interface=api).

```text
POST /{namespace}/entitlements/check
```

Body, as JSON: the inputs. Emits [`Entitlement.checked`](/business/events/Entitlement.checked).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `customer` | [Customer](/business/nouns/customer) | Yes | The Customer making the call. |
| `verb` | [Verb](/business/nouns/verb) | Yes | The Verb it wants to call, as `Noun.verb`. |
| `amount` | `integer` | No | How many units the call would use. Defaults to 1. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `allowed` | `boolean` | Yes | True when an Entitlement grants the call and its Limit has room for `amount`. |
| `entitlement` | [Entitlement](/business/nouns/entitlement) | No | The Entitlement that grants the Verb, when one does. |
| `remaining` | `integer` | No | Units left in the current period; absent for a `feature` Entitlement. |
| `resetsAt` | `datetime` | No | When the period resets; absent when the Limit never resets. |
| `upgrade` | [Offer](/business/nouns/offer) | No | The Offer that lifts the bound, when its Offer’s `atBound` is `upgrade`. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

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

```json
{
  "api": "https://api.sb/leaseline.app",
  "allowed": true,
  "entitlement": {
    "$id": "https://api.sb/leaseline.app/entitlements/ent_7MQACmrzGj",
    "$type": "Entitlement",
    "verb": "verb_hlkWBvrAyZ"
  },
  "remaining": 1,
  "resetsAt": "2026-10-22T12:00:00Z",
  "upgrade": {
    "$id": "https://api.sb/leaseline.app/offers/offer_HNonLXradP",
    "$type": "Offer",
    "price": {
      "amount": 29,
      "currency": "USD"
    }
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Entitlement.check",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```