# Demand Budget

URL: /business/nouns/demand-budget · Id: `noun:demand-budget`

> A Demand Budget is the money a founder commits each month to demand Plays, recorded as a Decision with a target and a stop rule.

A Demand Budget is the money a founder commits each month to demand [Plays](/business/nouns/play), recorded as a [Decision](/business/nouns/decision) with a target and a stop rule. A [Startup](/business/nouns/startup) without one runs at $0, on free Plays only.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | `money` | Yes | The monthly spend it funds; zero is the default. |
| `tier` | `string` | Yes | One of `$0`, `$100`, `$1k`, `$10k` or `$100k`: the highest tier at or below the amount, whose Play mix it buys. |
| `target` | `string` | Yes | The Metric value the spend must reach, such as cost per first Order under $40. |
| `stopRule` | `string` | Yes | The reading that closes the budget, such as acquisition cost above margin for two weeks. |
| `until` | `date` | No | The last day the budget runs before its Decision is read. |
| `status` | `string` | Yes | One of `Open`, `Stopped` or `Closed`. A closed budget is kept with its Evidence. |

## Object
```json
{
  "$id": "https://api.sb/routewise.dev/demand-budgets/demand_budget_1",
  "$type": "DemandBudget",
  "amount": {
    "amount": 25,
    "currency": "USD"
  },
  "tier": "$0",
  "target": "Example target",
  "stopRule": "Example stop rule",
  "until": "2026-10-22",
  "status": "Open"
}
```

## Relationships
- <a id="rel-allocated-by"></a>A Demand Budget **is allocated by** many [Play Mixes](/business/nouns/play-mix): each [Play Mix](/business/nouns/play-mix) version splits one Demand Budget across its paid [Plays](/business/nouns/play). `allocatedBy`, inverse [`allocates`](/business/nouns/play-mix#rel-allocates).
- <a id="rel-funded-by"></a>A Demand Budget **is funded by** one [Startup](/business/nouns/startup): a [Startup](/business/nouns/startup) commits monthly Demand Budgets, each with a target and a stop rule. `fundedBy`, inverse [`funds`](/business/nouns/startup#rel-funds).
- <a id="rel-pays"></a>A Demand Budget **pays** many [Plays](/business/nouns/play): a Demand Budget’s spend buys demand [Plays](/business/nouns/play). `pays`, inverse [`paidBy`](/business/nouns/play#rel-paid-by).
- <a id="rel-recorded-as"></a>A Demand Budget **is recorded as** one [Decision](/business/nouns/decision): each Demand Budget is committed as one [Decision](/business/nouns/decision), read again when it closes. `recordedAs`, inverse [`records`](/business/nouns/decision#rel-records).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[DemandBudget.create](/business/nouns/demand-budget/create) | Creates a Demand Budget. Inherited from [Noun](/business/nouns/noun). | None. | `DemandBudget.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[DemandBudget.get](/business/nouns/demand-budget/get) | Returns one Demand Budget by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[DemandBudget.list](/business/nouns/demand-budget/list) | Returns Demand Budgets, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[DemandBudget.update](/business/nouns/demand-budget/update) | Changes the given properties of a Demand Budget. Inherited from [Noun](/business/nouns/noun). | None. | `DemandBudget.updated` | Two-way: `try`, `send`, `do` |

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

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `DemandBudget.create` | Yes | Yes | Yes | No |
| `DemandBudget.get` | Yes | Yes | Yes | Yes |
| `DemandBudget.list` | Yes | Yes | Yes | Yes |
| `DemandBudget.update` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a demand budget to TutorLoop.
```

**API**

```bash
curl -X POST https://api.sb/tutorloop.com/demand-budgets \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"amount":60,"currency":"USD"},"tier":"$0","target":"Example target","stopRule":"Example stop rule"}'
```

```json
{
  "api": "https://api.sb/tutorloop.com",
  "demandBudget": {
    "$id": "https://api.sb/tutorloop.com/demand-budgets/demand_budget_1",
    "$type": "DemandBudget",
    "amount": {
      "amount": 60,
      "currency": "USD"
    },
    "tier": "$0",
    "target": "Example target",
    "stopRule": "Example stop rule"
  },
  "action": {
    "$id": "https://api.sb/tutorloop.com/actions/action_1",
    "operation": "DemandBudget.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/tutorloop.com/actions/action_1"
  }
}
```

**SDK**

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

const demandBudget = await $.DemandBudget.create({ amount: { amount: 60, currency: 'USD' }, tier: '$0', target: 'Example target', stopRule: 'Example stop rule' })
```

**CLI**

```bash
npx startup-builder do DemandBudget.create --json '{"amount":{"amount":60,"currency":"USD"},"tier":"$0","target":"Example target","stopRule":"Example stop rule"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.DemandBudget.create({ amount: { amount: 60, currency: 'USD' }, tier: '$0', target: 'Example target', stopRule: 'Example stop rule' })"
  }
}
```

## Example
A founder funds a $1,000 Demand Budget for a Startup selling a scheduling app to dental offices. Its target is cost per first [Order](/business/nouns/order) under $90, and its stop rule closes it if cost runs higher for two weeks. [Marketing](/workflows/marketing/demand-budgets) spends it on one paid search [Campaign](/business/nouns/campaign).