# Customer

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

> A Customer is a party that has accepted an Offer from a Startup at any price, including zero.

A Customer is a party that has accepted an [Offer](/business/nouns/offer) from a [Startup](/business/nouns/startup) at any price, including zero. Interest alone makes a [Lead](/business/nouns/lead), not a Customer.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `since` | `datetime` | Yes | When the party first accepted an Offer. |
| `outside` | `boolean` | No | Computed: true when it shares no owner, account, or sibling chain with the Startup. |
| `status` | `string` | No | One of `trialing`, `activated`, `atRisk`, `churned`, or `wonBack`, computed from Events and never set by hand; `atRisk` reads customer health. |
| `billingEmail` | `email` | No | Where Invoices and receipts go, when it differs from the sign-in email. |
| `billingAddress` | `text` | No | The address printed on new Invoices; Stripe Tax reads it to compute tax. |
| `taxIds` | `string[]` | No | The Customer’s tax ids, such as a VAT number, printed on new Invoices and read by Stripe Tax. |
| `creditRecharge` | `json` | No | When unspent credit falls below `below`, buy `amount` of the credit Offer with the default Payment Source. |

## Object
```json
{
  "$id": "https://api.sb/kilnbakery.com/customers/customer_1",
  "$type": "Customer",
  "since": "2026-10-22T12:00:00Z",
  "outside": true,
  "status": "trialing",
  "billingEmail": "tomas@kilnbakery.com",
  "billingAddress": "Example billing address",
  "taxIds": [
    "Example tax ids"
  ],
  "creditRecharge": {}
}
```

## Relationships
- <a id="rel-accepts"></a>A Customer **accepts** many [Offers](/business/nouns/offer): a party becomes a Customer by accepting any [Offer](/business/nouns/offer), at any price including zero. `accepts`, inverse [`acceptedBy`](/business/nouns/offer#rel-accepted-by).
- <a id="rel-acquired-by"></a>A Customer **is acquired by** one [Acquisition](/business/nouns/acquisition): a Customer inherits the [Acquisition](/business/nouns/acquisition) of the [Lead](/business/nouns/lead) it was; [Metrics](/business/nouns/metric) and payouts read this one row. `acquiredBy`, inverse [`customers`](/business/nouns/acquisition#rel-customers).
- <a id="rel-contact"></a>A Customer **has** one [Contact](/business/nouns/contact): a [Contact](/business/nouns/contact) becomes a Customer on accepting an [Offer](/business/nouns/offer). `contact`, inverse [`becomes`](/business/nouns/contact#rel-becomes).
- <a id="rel-credit-grants"></a>A Customer **has** many [Credit Grants](/business/nouns/credit-grant): the Customer whose metered calls spend the balance; credits never move to another Customer. `creditGrants`, inverse [`credits`](/business/nouns/credit-grant#rel-credits).
- <a id="rel-holds"></a>A Customer **holds** many [Entitlements](/business/nouns/entitlement): a Customer’s [Entitlements](/business/nouns/entitlement) are what it may do right now, granted by the [Offers](/business/nouns/offer) it accepted. `holds`, inverse [`heldBy`](/business/nouns/entitlement#rel-held-by).
- <a id="rel-invoices"></a>A Customer **has** many [Invoices](/business/nouns/invoice): each [Invoice](/business/nouns/invoice) is owed by one Customer. `invoices`, inverse [`charges`](/business/nouns/invoice#rel-charges).
- <a id="rel-maintains"></a>A Customer **maintains** many [Subscriptions](/business/nouns/subscription): a Customer holds [Subscriptions](/business/nouns/subscription), each billed once per [Period](/business/nouns/period). `maintains`, inverse [`subscriber`](/business/nouns/subscription#rel-subscriber).
- <a id="rel-opens"></a>A Customer **opens** many [Conversations](/business/nouns/conversation): the Customer a [Conversation](/business/nouns/conversation) serves, so every answer reads that Customer’s records. `opens`, inverse [`customer`](/business/nouns/conversation#rel-customer).
- <a id="rel-owns"></a>A Customer **owns** one [Tenant](/business/nouns/tenant): each Customer has one [Tenant](/business/nouns/tenant): the partition of the [Startup](/business/nouns/startup)’s data that no other Customer reads. `owns`, inverse [`ownedBy`](/business/nouns/tenant#rel-owned-by).
- <a id="rel-places"></a>A Customer **places** many [Orders](/business/nouns/order): a Customer commits to one-time purchases as [Orders](/business/nouns/order). `places`, inverse [`placedBy`](/business/nouns/order#rel-placed-by).
- <a id="rel-saves"></a>A Customer **saves** many [Payment Sources](/business/nouns/payment-source): a Customer saves the [Payment Sources](/business/nouns/payment-source) its [Orders](/business/nouns/order), [Subscriptions](/business/nouns/subscription) and [Invoices](/business/nouns/invoice) charge; each belongs to one [Startup](/business/nouns/startup) and never moves to a sibling. `saves`, inverse [`savedBy`](/business/nouns/payment-source#rel-saved-by).
- <a id="rel-served-by"></a>A Customer **is served by** one [Startup](/business/nouns/startup): a [Startup](/business/nouns/startup) serves every party that has accepted one of its [Offers](/business/nouns/offer). `servedBy`, inverse [`serves`](/business/nouns/startup#rel-serves).
- <a id="rel-signs-into"></a>A Customer **signs into** one [Portal](/business/nouns/portal): Customers sign in to a [Portal](/business/nouns/portal) to order, track delivery, accept work, and pay. `signsInto`, inverse [`serves`](/business/nouns/portal#rel-serves).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `trialing` (first) | It accepted an Offer and has not yet reached the Offer’s activation Event. | `activated` on [`Customer.activated`](/business/events/Customer.activated); `churned` on [`Subscription.unsubscribed`](/business/events/Subscription.unsubscribed) when it ends its last active Subscription |
| `activated` | It reached its Offer’s activation Event within the window and pays on time. | `atRisk` on [`Subscription.pastDue`](/business/nouns/subscription#subscriptionpastdue) when the Subscription is this Customer’s; `atRisk` on [`Dispute.opened`](/business/nouns/dispute#disputeopened) when the disputed charge is this Customer’s; `churned` on [`Subscription.unsubscribed`](/business/events/Subscription.unsubscribed) when it ends its last active Subscription |
| `atRisk` | A renewal is past due, a Dispute is open, or its health reading fell below the line. | `activated` on [`Invoice.collected`](/business/events/Invoice.collected) when the overdue Invoice is this Customer’s; `churned` on [`Subscription.unsubscribed`](/business/events/Subscription.unsubscribed) when it ends its last active Subscription |
| `churned` | It holds no active Subscription and placed no Order in the window; its record stays. | `wonBack` on [`Offer.subscribed`](/business/events/Offer.subscribed) when the subscriber is this Customer; `wonBack` on [`Order.placed`](/business/events/Order.placed) when the buyer is this Customer |
| `wonBack` | A churned Customer that subscribed or bought again. | `atRisk` on [`Subscription.pastDue`](/business/nouns/subscription#subscriptionpastdue) when the Subscription is this Customer’s; `churned` on [`Subscription.unsubscribed`](/business/events/Subscription.unsubscribed) when it ends its last active Subscription |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Offer.accept](/business/nouns/offer/accept) | Accept records that a party takes an Offer, which makes that party a Customer of the Startup. | [Customer](/business/nouns/customer) | [`Offer.accepted`](/business/events/Offer.accepted) | None. |
| [Quote.accept](/business/nouns/quote/accept) | Accept takes a sent Quote before it expires, turning one-time lines into an Order and recurring lines into a Subscription. | [Sales Engineer](/agents/sales/sales-engineer) | [`Quote.accepted`](/business/events/Quote.accepted) | One-way: `send`, `do` |
| [Customer.activate](/business/nouns/customer/activate) | Activate marks a Customer activated on an Offer once its declared activation Event reaches the count within the window. | [Analyst](/agents/marketing/analyst) | [`Customer.activated`](/business/events/Customer.activated) | Two-way: `try`, `send`, `do` |
| [PaymentSource.add](/business/nouns/payment-source/add) | Add saves a new Payment Source for a Customer through Stripe’s embedded form on the Startup’s Domain, and can make it the default. | [Billing Specialist](/agents/finance/billing-specialist) | [`PaymentSource.added`](/business/events/PaymentSource.added) | Two-way: `try`, `send`, `do` |
| [Order.cancel](/business/nouns/order/cancel) | Cancel ends an Order before fulfillment and returns any payment in full. | [Customer](/business/nouns/customer) | [`Order.canceled`](/business/events/Order.canceled) | Two-way: `try`, `send`, `do` |
| [Order.confirm](/business/nouns/order/confirm) | Confirm records the Customer’s sign-off on delivered work, which closes the Order and earns the Startup its fee. | [Delivery Manager](/agents/operations/delivery-manager) | [`Order.confirmed`](/business/events/Order.confirmed) | One-way (money): `send`, `do` |
| [Order.dispute](/business/nouns/order/dispute) | Dispute contests a delivered Order under its Outcome Contract and starts the remedy the contract names. | [Billing Specialist](/agents/finance/billing-specialist) | [`Order.disputed`](/business/events/Order.disputed) | Two-way: `try`, `send`, `do` |
| [Customer.exempt](/business/nouns/customer/exempt) | Exempt records a Customer’s exemption or resale certificate, verifies it, and stops tax on its Orders where the certificate applies. | [Finance Lead](/agents/finance/finance-lead) | [`Customer.exempted`](/business/events/Customer.exempted) | Two-way: `try`, `send`, `do` |
| [Tenant.invite](/business/nouns/tenant/invite) | Invite asks a Person to join a Customer’s Tenant, and resizes the Subscription when the Offer prices per member. | [Security Engineer](/agents/engineering/security-engineer) | [`Tenant.invited`](/business/events/Tenant.invited) | Two-way: `try`, `send`, `do` |
| [Subscription.keep](/business/nouns/subscription/keep) | Keep takes back a cancel before the period closes, so the Subscription renews on its date at the same terms. | [Billing Specialist](/agents/finance/billing-specialist) | [`Subscription.kept`](/business/events/Subscription.kept) | Two-way: `try`, `send`, `do` |
| [Subscription.pause](/business/nouns/subscription/pause) | Pause stops billing and Entitlements on a Subscription until a date, without ending it. | [Billing Specialist](/agents/finance/billing-specialist) | [`Subscription.paused`](/business/events/Subscription.paused) | Two-way: `try`, `send`, `do` |
| [Order.pay](/business/nouns/order/pay) | Pay settles an Order’s amount through the Startup’s payment account and posts the matching Entries. | [Billing Specialist](/agents/finance/billing-specialist) | [`Order.paid`](/business/events/Order.paid) | One-way (money): `send`, `do` |
| [Tenant.pin](/business/nouns/tenant/pin) | Pin moves a Tenant’s keys to another API version, or to `latest`, once a call with its test key passes there. | [Customer](/business/nouns/customer) | [`Tenant.pinned`](/business/events/Tenant.pinned) | Two-way: `try`, `send`, `do` |
| [Order.place](/business/nouns/order/place) | Place commits a Customer to buy an Offer once and records the Offer Version and price at that moment. | [Founder](/agents/founding/founder) | [`Order.placed`](/business/events/Order.placed) | Two-way: `try`, `send`, `do` |
| [PaymentSource.remove](/business/nouns/payment-source/remove) | Remove detaches a saved Payment Source so nothing charges it again, and keeps the record. | [Billing Specialist](/agents/finance/billing-specialist) | [`PaymentSource.removed`](/business/events/PaymentSource.removed) | Two-way: `try`, `send`, `do` |
| [Subscription.resize](/business/nouns/subscription/resize) | Resize changes how many units a Subscription holds and prorates the current period. | [Billing Specialist](/agents/finance/billing-specialist) | [`Subscription.resized`](/business/events/Subscription.resized) | Two-way: `try`, `send`, `do` |
| [Subscription.resume](/business/nouns/subscription/resume) | Resume restarts billing and Entitlements on a paused Subscription before its pause ends. | [Billing Specialist](/agents/finance/billing-specialist) | [`Subscription.resumed`](/business/events/Subscription.resumed) | Two-way: `try`, `send`, `do` |
| [Order.revise](/business/nouns/order/revise) | Revise sends delivered lines back for one counted revision, with the changes the Customer asks for. | [Delivery Manager](/agents/operations/delivery-manager) | [`Order.revised`](/business/events/Order.revised) | Two-way: `try`, `send`, `do` |
| [Offer.subscribe](/business/nouns/offer/subscribe) | Subscribe accepts a recurring Offer as a Subscription that renews each period until it ends. | [Billing Specialist](/agents/finance/billing-specialist) | [`Offer.subscribed`](/business/events/Offer.subscribed) | None. |
| [Subscription.switch](/business/nouns/subscription/switch) | Switch moves a Subscription to another Offer and prorates the current period. | [Billing Specialist](/agents/finance/billing-specialist) | [`Subscription.switched`](/business/events/Subscription.switched) | Two-way: `try`, `send`, `do` |
| [Offer.trial](/business/nouns/offer/trial) | Trial starts a Customer on an Offer free for a set number of days, with or without a card, converting or ending by its terms. | [Billing Specialist](/agents/finance/billing-specialist) | [`Offer.trialed`](/business/events/Offer.trialed) | Two-way: `try`, `send`, `do` |
| [Subscription.unsubscribe](/business/nouns/subscription/unsubscribe) | Unsubscribe ends a Subscription at the close of its current period, and the Customer keeps access until then. | [Billing Specialist](/agents/finance/billing-specialist) | [`Subscription.unsubscribed`](/business/events/Subscription.unsubscribed) | Two-way: `try`, `send`, `do` |
| <a id="create"></a>[Customer.create](/business/nouns/customer/create) | Creates a Customer. Inherited from [Noun](/business/nouns/noun). | None. | `Customer.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Customer.get](/business/nouns/customer/get) | Returns one Customer by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Customer.list](/business/nouns/customer/list) | Returns Customers, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="update"></a>[Customer.update](/business/nouns/customer/update) | Changes the given properties of a Customer. Inherited from [Noun](/business/nouns/noun). | None. | `Customer.updated` | Two-way: `try`, `send`, `do` |
| <a id="delete"></a>[Customer.delete](/business/nouns/customer/delete) | Deletes a Customer; its history is kept. Inherited from [Noun](/business/nouns/noun). | None. | `Customer.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` |
| --- | --- | --- | --- | --- |
| `Customer.create` | Yes | Yes | Yes | No |
| `Customer.get` | Yes | Yes | Yes | Yes |
| `Customer.list` | Yes | Yes | Yes | Yes |
| `Customer.update` | Yes | Yes | Yes | No |
| `Customer.delete` | Yes | Yes | Yes | No |
| `Customer.activate` | Yes | Yes | Yes | No |
| `Customer.exempt` | Yes | Yes | Yes | No |

## Stripe
**Customer** (`customer`). The source of truth is db.sb, and Stripe holds a copy written from it.

| Property | Stripe field | Source of truth |
| --- | --- | --- |
| `billingEmail` | `email` | db.sb |
| `billingAddress` | `address` | db.sb |
| `taxIds` | `tax_ids.data[].value` | db.sb |

## Call it

**Ask**

```text
Activate the latest customer with an offer.
```

**API**

```bash
curl -X POST https://api.sb/patentpad.com/customers/customer_1/activate \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"offer":"offer_1"}'
```

```json
{
  "api": "https://api.sb/patentpad.com",
  "customer": {
    "$id": "https://api.sb/patentpad.com/customers/customer_1",
    "$type": "Customer",
    "since": "2026-10-22T12:00:00Z"
  },
  "action": {
    "$id": "https://api.sb/patentpad.com/actions/action_1",
    "operation": "Customer.activate",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/patentpad.com/actions/action_1"
  }
}
```

**SDK**

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

const customer = await $.Customer.activate({ customer: 'customer_1', offer: 'offer_1' })
```

**CLI**

```bash
npx startup-builder do Customer.activate --json '{"customer":"customer_1","offer":"offer_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Customer.activate({ customer: 'customer_1', offer: 'offer_1' })"
  }
}
```

## Example
A developer who takes a $0 API key accepts an Offer and becomes a Customer, with `since` set to that day. A developer who joins the [Waitlist](/business/nouns/waitlist) accepts nothing and stays a Lead.