# Credit Grant

URL: /business/nouns/credit-grant · Id: `noun:credit-grant`

> A Credit Grant is a prepaid or promotional balance a Customer spends on a Startup’s metered Offers, checked before each call.

A Credit Grant is a prepaid or promotional balance a [Customer](/business/nouns/customer) spends on a [Startup](/business/nouns/startup)’s metered [Offers](/business/nouns/offer), checked before each call.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | `money` | Yes | The balance granted. Never randomized. |
| `category` | `string` | Yes | `paid` (bought through an Order, deferred revenue until spent) or `promotional` (given; never cash). Never randomized. |
| `priority` | `integer` | No | Order of use when several grants apply: a lower number spends first, then the earliest expiry. |
| `expiresAt` | `datetime` | No | When any remaining balance lapses. Absent means it never lapses. |
| `appliesTo` | [Offer](/business/nouns/offer) | No | The metered Offer the balance pays for. Absent means every metered Offer of the Startup. |
| `remaining` | `money` | No | The unspent balance, debited once after each metered call and checked as a Limit before the next. |

## Object
```json
{
  "$id": "https://api.sb/tutorloop.com/credit-grants/credit_grant_1",
  "$type": "CreditGrant",
  "amount": {
    "amount": 60,
    "currency": "USD"
  },
  "category": "paid",
  "priority": 1,
  "expiresAt": "2026-10-22T12:00:00Z",
  "appliesTo": "offer_1",
  "remaining": {
    "amount": 60,
    "currency": "USD"
  }
}
```

## Relationships
- <a id="rel-credits"></a>A Credit Grant **credits** one [Customer](/business/nouns/customer): the [Customer](/business/nouns/customer) whose metered calls spend the balance; credits never move to another Customer. `credits`, inverse [`creditGrants`](/business/nouns/customer#rel-credit-grants).
- <a id="rel-offsets"></a>A Credit Grant **offsets** many [Invoices](/business/nouns/invoice): the [Invoices](/business/nouns/invoice) the grant paid toward when they finalized. `offsets`, inverse [`creditGrants`](/business/nouns/invoice#rel-credit-grants).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [CreditGrant.apply](/business/nouns/credit-grant/apply) | Apply spends Credit Grants against a finalizing Invoice, promotional first, then by priority and earliest expiry, and settles them through Stripe credit grants. | [Billing Specialist](/agents/finance/billing-specialist) | [`CreditGrant.applied`](/business/events/CreditGrant.applied) | Two-way: `try`, `send`, `do` |
| [CreditGrant.issue](/business/nouns/credit-grant/issue) | Issue gives a Customer a paid or promotional Credit Grant that its metered calls draw down before anything is invoiced. | [Billing Specialist](/agents/finance/billing-specialist) | [`CreditGrant.issued`](/business/events/CreditGrant.issued) | Two-way: `try`, `send`, `do` |
| [CreditGrant.void](/business/nouns/credit-grant/void) | Void ends a promotional Credit Grant early and forfeits its remaining balance, keeping the record. | [Billing Specialist](/agents/finance/billing-specialist) | [`CreditGrant.voided`](/business/events/CreditGrant.voided) | One-way (customer): `send`, `do` |
| <a id="create"></a>[CreditGrant.create](/business/nouns/credit-grant/create) | Creates a Credit Grant. Inherited from [Noun](/business/nouns/noun). | None. | `CreditGrant.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[CreditGrant.get](/business/nouns/credit-grant/get) | Returns one Credit Grant by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[CreditGrant.list](/business/nouns/credit-grant/list) | Returns Credit Grants, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

A Credit Grant is never deleted: it ends by [CreditGrant.void](/business/nouns/credit-grant/void), and its records stay.

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

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `CreditGrant.create` | Yes | Yes | Yes | No |
| `CreditGrant.get` | Yes | Yes | Yes | Yes |
| `CreditGrant.list` | Yes | Yes | Yes | Yes |
| `CreditGrant.apply` | Yes | Yes | Yes | No |
| `CreditGrant.issue` | Yes | Yes | Yes | No |
| `CreditGrant.void` | Yes | No | No | No |

## Call it

**Ask**

```text
Apply the latest credit grant with an invoice.
```

**API**

```bash
curl -X POST https://api.sb/patentpad.com/credit-grants/apply \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice":"invoice_1"}'
```

```json
{
  "api": "https://api.sb/patentpad.com",
  "applied": {
    "amount": 499,
    "currency": "USD"
  },
  "creditGrants": [
    {
      "$id": "https://api.sb/patentpad.com/credit-grants/credit_grant_1",
      "$type": "CreditGrant",
      "amount": {
        "amount": 499,
        "currency": "USD"
      },
      "category": "paid"
    }
  ],
  "action": {
    "$id": "https://api.sb/patentpad.com/actions/action_1",
    "operation": "CreditGrant.apply",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/patentpad.com/actions/action_1"
  }
}
```

**SDK**

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

const { applied, creditGrants } = await $.CreditGrant.apply({ invoice: 'invoice_1' })
```

**CLI**

```bash
npx startup-builder do CreditGrant.apply --json '{"invoice":"invoice_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.CreditGrant.apply({ invoice: 'invoice_1' })"
  }
}
```

## Example
A transcription API sells a $100 `paid` Credit Grant and adds a $20 `promotional` grant with priority 1. Each metered call spends the promotional balance first, then the paid one, and a call stops when both reach zero.