# Coupon

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

> A Coupon is a discount on Offers, by amount or percent, for one charge, several months or every charge, limited by date and redemptions.

A Coupon is a discount on [Offers](/business/nouns/offer), by amount or percent, for one charge, several months or every charge, limited by date and redemptions.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `percentOff` | `number` | No | The percent taken off each charge it applies to; set this or `amountOff`. Never randomized. |
| `amountOff` | `money` | No | The fixed amount taken off each charge it applies to. Never randomized. |
| `duration` | `string` | Yes | How long it applies: `once`, `repeating` for `months`, or `forever`. |
| `months` | `integer` | No | How many months a `repeating` Coupon applies. |
| `code` | `string` | No | The promotion code a buyer types at checkout, when the Coupon has one. |
| `redeemBy` | `datetime` | No | The last moment it can be redeemed. |
| `maxRedemptions` | `integer` | No | How many times it can be redeemed across all Customers. |

## Object
```json
{
  "$id": "https://api.sb/tutorloop.com/coupons/coupon_1",
  "$type": "Coupon",
  "percentOff": 1,
  "amountOff": {
    "amount": 60,
    "currency": "USD"
  },
  "duration": "once",
  "months": 1,
  "code": "LAUNCH20",
  "redeemBy": "2026-10-22T12:00:00Z",
  "maxRedemptions": 1
}
```

## Relationships
- <a id="rel-discounts"></a>A Coupon **discounts** many [Offers](/business/nouns/offer): a Coupon applies only to the [Offers](/business/nouns/offer) it names; an Offer may accept several Coupons. `discounts`, inverse [`coupons`](/business/nouns/offer#rel-coupons).

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| <a id="create"></a>[Coupon.create](/business/nouns/coupon/create) | Creates a Coupon. Inherited from [Noun](/business/nouns/noun). | None. | `Coupon.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Coupon.get](/business/nouns/coupon/get) | Returns one Coupon by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Coupon.list](/business/nouns/coupon/list) | Returns Coupons, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Coupon.update](/business/nouns/coupon/update) | Changes the given properties of a Coupon. Inherited from [Noun](/business/nouns/noun). | None. | `Coupon.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` |
| --- | --- | --- | --- | --- |
| `Coupon.create` | Yes | Yes | Yes | No |
| `Coupon.get` | Yes | Yes | Yes | Yes |
| `Coupon.list` | Yes | Yes | Yes | Yes |
| `Coupon.update` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Add a coupon to QuietCopy.
```

**API**

```bash
curl -X POST https://api.sb/quietcopy.com/coupons \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"duration":"once"}'
```

```json
{
  "api": "https://api.sb/quietcopy.com",
  "coupon": {
    "$id": "https://api.sb/quietcopy.com/coupons/coupon_1",
    "$type": "Coupon",
    "duration": "once"
  },
  "action": {
    "$id": "https://api.sb/quietcopy.com/actions/action_1",
    "operation": "Coupon.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/quietcopy.com/actions/action_1"
  }
}
```

**SDK**

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

const coupon = await $.Coupon.create({ duration: 'once' })
```

**CLI**

```bash
npx startup-builder do Coupon.create --json '{"duration":"once"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Coupon.create({ duration: 'once' })"
  }
}
```

## Example
A design tool offers the code `LAUNCH30`: 30% off for 3 months on its yearly and monthly [Offers](/business/nouns/offer). It can be redeemed 500 times before the end of the month.