# Billing

URL: /systems/billing · Id: `system:billing`

> Billing turns accepted Offers into Orders, Subscriptions, Invoices, metered usage and Entitlements on Stripe, with checkout and dunning.

Billing charges [Customers](/business/nouns/customer) for accepted [Offers](/business/nouns/offer): checkout, [Subscriptions](/business/nouns/subscription), [Invoices](/business/nouns/invoice), metered usage and [Entitlements](/business/nouns/entitlement), with dunning when a payment fails. It runs on Stripe, which the platform wraps rather than rebuilds.

## Summary
| Part | This System |
| --- | --- |
| Group | Finance |
| Status | Live |
| Shelf | Front: offered from a Startup’s first days |

You can ask:

- “Charge customers monthly”
- “Send this customer an invoice”
- “Retry the payments that failed”
- “Refund this order”
- “Show me who is past due”

## What you get
| Part | This System |
| --- | --- |
| Starts | On for every Startup at creation, with nothing to install. |
| Built from | [Payment rails](/systems/finance/payments), [Database](/code/platform/capabilities/database), [Event streams](/code/platform/event-streams), [Workflows](/code/platform/workflows) |

## Nouns it owns
| Noun | Definition |
| --- | --- |
| [Order](/business/nouns/order) | An Order is a Customer’s commitment to buy one or more Offers once, moving from placed to paid, fulfilled, and closed. |
| [Subscription](/business/nouns/subscription) | A Subscription is a Customer’s standing acceptance of an Offer, billed each Period until canceled. |
| [Invoice](/business/nouns/invoice) | An Invoice is what a Customer owes for one or more Offers over one billing period. |
| [Meter](/business/nouns/meter) | A Meter is a billable measure of usage that turns usage Events into Entries exactly once. |
| [Entitlement](/business/nouns/entitlement) | An Entitlement is what a Customer gets from an accepted Offer: a Verb on a Noun in its Tenant, optionally bounded by a Limit. |
| [Dispute](/business/nouns/dispute) | A Dispute is a contested payment or delivery, such as a chargeback, a rejected Service outcome, or a buyer’s claim against a Supplier. |
| [Credit Grant](/business/nouns/credit-grant) | A Credit Grant is a prepaid or promotional balance a Customer spends on a Startup’s metered Offers, checked before each call. |
| [Offer](/business/nouns/offer) | An Offer is a Product, under a Brand, at a price, on terms, made by a Startup. |
| [Price](/business/nouns/price) | A Price is the amount, currency, unit, and tiers of an Offer, embedded in it; zero is a Price. |
| [Coupon](/business/nouns/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. |
| [Payment Source](/business/nouns/payment-source) | A Payment Source is a card, bank debit or wallet a Customer saves with a Startup, held at Stripe and charged for Orders and Invoices. |

## Verbs
| Verb | Object | Approval | Event |
| --- | --- | --- | --- |
| [Offer.subscribe](/business/nouns/offer/subscribe) | [Offer](/business/nouns/offer) | None | [`Offer.subscribed`](/business/events/Offer.subscribed) |
| [Subscription.renew](/business/nouns/subscription/renew) | [Subscription](/business/nouns/subscription) | None | [`Subscription.renewed`](/business/events/Subscription.renewed) |
| [Subscription.switch](/business/nouns/subscription/switch) | [Subscription](/business/nouns/subscription) | None | [`Subscription.switched`](/business/events/Subscription.switched) |
| [Subscription.unsubscribe](/business/nouns/subscription/unsubscribe) | [Subscription](/business/nouns/subscription) | None | [`Subscription.unsubscribed`](/business/events/Subscription.unsubscribed) |
| [Order.pay](/business/nouns/order/pay) | [Order](/business/nouns/order) | Asks first; waits 1 business hour | [`Order.paid`](/business/events/Order.paid) |
| [Order.refund](/business/nouns/order/refund) | [Order](/business/nouns/order) | Asks first; waits 1 business hour | [`Order.refunded`](/business/events/Order.refunded) |
| [Invoice.bill](/business/nouns/invoice/bill) | [Invoice](/business/nouns/invoice) | Asks first; waits 1 business hour | [`Invoice.billed`](/business/events/Invoice.billed) |
| [Invoice.collect](/business/nouns/invoice/collect) | [Invoice](/business/nouns/invoice) | Asks first; waits 1 business hour | [`Invoice.collected`](/business/events/Invoice.collected) |
| [Subscription.resize](/business/nouns/subscription/resize) | [Subscription](/business/nouns/subscription) | None | [`Subscription.resized`](/business/events/Subscription.resized) |
| [Subscription.pause](/business/nouns/subscription/pause) | [Subscription](/business/nouns/subscription) | None | [`Subscription.paused`](/business/events/Subscription.paused) |
| [Subscription.resume](/business/nouns/subscription/resume) | [Subscription](/business/nouns/subscription) | None | [`Subscription.resumed`](/business/events/Subscription.resumed) |
| [CreditGrant.apply](/business/nouns/credit-grant/apply) | [Credit Grant](/business/nouns/credit-grant) | None | [`CreditGrant.applied`](/business/events/CreditGrant.applied) |
| [CreditGrant.void](/business/nouns/credit-grant/void) | [Credit Grant](/business/nouns/credit-grant) | Asks first; waits 1 business hour | [`CreditGrant.voided`](/business/events/CreditGrant.voided) |
| [Offer.trial](/business/nouns/offer/trial) | [Offer](/business/nouns/offer) | None | [`Offer.trialed`](/business/events/Offer.trialed) |
| [Coupon.create](/business/nouns/coupon/create) | [Coupon](/business/nouns/coupon) | None | `Coupon.created` |
| [Dispute.answer](/business/nouns/dispute/answer) | [Dispute](/business/nouns/dispute) | Asks first; waits 1 business hour | [`Dispute.answered`](/business/events/Dispute.answered) |
| [Dispute.decide](/business/nouns/dispute/decide) | [Dispute](/business/nouns/dispute) | Asks first; waits 1 business hour | [`Dispute.decided`](/business/events/Dispute.decided) |
| [PaymentSource.add](/business/nouns/payment-source/add) | [Payment Source](/business/nouns/payment-source) | None | [`PaymentSource.added`](/business/events/PaymentSource.added) |
| [PaymentSource.remove](/business/nouns/payment-source/remove) | [Payment Source](/business/nouns/payment-source) | None | [`PaymentSource.removed`](/business/events/PaymentSource.removed) |
| [Invoice.void](/business/nouns/invoice/void) | [Invoice](/business/nouns/invoice) | Asks first; waits 1 business hour | [`Invoice.voided`](/business/events/Invoice.voided) |
| [Invoice.refund](/business/nouns/invoice/refund) | [Invoice](/business/nouns/invoice) | Asks first; waits 1 business hour | [`Invoice.refunded`](/business/events/Invoice.refunded) |
| [Subscription.keep](/business/nouns/subscription/keep) | [Subscription](/business/nouns/subscription) | None | [`Subscription.kept`](/business/events/Subscription.kept) |
| [CreditGrant.issue](/business/nouns/credit-grant/issue) | [Credit Grant](/business/nouns/credit-grant) | None | [`CreditGrant.issued`](/business/events/CreditGrant.issued) |
| [Dispute.accept](/business/nouns/dispute/accept) | [Dispute](/business/nouns/dispute) | Asks first; waits 1 business hour | [`Dispute.accepted`](/business/events/Dispute.accepted) |
| [Dispute.appeal](/business/nouns/dispute/appeal) | [Dispute](/business/nouns/dispute) | Asks first; waits 1 business hour | [`Dispute.appealed`](/business/events/Dispute.appealed) |

## Events
| Direction | Event | How |
| --- | --- | --- |
| Emits | [`Offer.subscribed`](/business/events/Offer.subscribed) | By [Offer.subscribe](/business/nouns/offer/subscribe) |
| Emits | [`Subscription.renewed`](/business/events/Subscription.renewed) | By [Subscription.renew](/business/nouns/subscription/renew) |
| Emits | [`Subscription.switched`](/business/events/Subscription.switched) | By [Subscription.switch](/business/nouns/subscription/switch) |
| Emits | [`Subscription.unsubscribed`](/business/events/Subscription.unsubscribed) | By [Subscription.unsubscribe](/business/nouns/subscription/unsubscribe) |
| Emits | [`Order.paid`](/business/events/Order.paid) | By [Order.pay](/business/nouns/order/pay) |
| Emits | [`Order.refunded`](/business/events/Order.refunded) | By [Order.refund](/business/nouns/order/refund) |
| Emits | [`Invoice.billed`](/business/events/Invoice.billed) | By [Invoice.bill](/business/nouns/invoice/bill) |
| Emits | [`Invoice.collected`](/business/events/Invoice.collected) | By [Invoice.collect](/business/nouns/invoice/collect) |
| Emits | [`Subscription.resized`](/business/events/Subscription.resized) | By [Subscription.resize](/business/nouns/subscription/resize) |
| Emits | [`Subscription.paused`](/business/events/Subscription.paused) | By [Subscription.pause](/business/nouns/subscription/pause) |
| Emits | [`Subscription.resumed`](/business/events/Subscription.resumed) | By [Subscription.resume](/business/nouns/subscription/resume) |
| Emits | [`CreditGrant.applied`](/business/events/CreditGrant.applied) | By [CreditGrant.apply](/business/nouns/credit-grant/apply) |
| Emits | [`CreditGrant.voided`](/business/events/CreditGrant.voided) | By [CreditGrant.void](/business/nouns/credit-grant/void) |
| Emits | [`Offer.trialed`](/business/events/Offer.trialed) | By [Offer.trial](/business/nouns/offer/trial) |
| Emits | `Coupon.created` | By [Coupon.create](/business/nouns/coupon/create) |
| Emits | [`Dispute.answered`](/business/events/Dispute.answered) | By [Dispute.answer](/business/nouns/dispute/answer) |
| Emits | [`Dispute.decided`](/business/events/Dispute.decided) | By [Dispute.decide](/business/nouns/dispute/decide) |
| Emits | [`PaymentSource.added`](/business/events/PaymentSource.added) | By [PaymentSource.add](/business/nouns/payment-source/add) |
| Emits | [`PaymentSource.removed`](/business/events/PaymentSource.removed) | By [PaymentSource.remove](/business/nouns/payment-source/remove) |
| Emits | [`Invoice.voided`](/business/events/Invoice.voided) | By [Invoice.void](/business/nouns/invoice/void) |
| Emits | [`Invoice.refunded`](/business/events/Invoice.refunded) | By [Invoice.refund](/business/nouns/invoice/refund) |
| Emits | [`Subscription.kept`](/business/events/Subscription.kept) | By [Subscription.keep](/business/nouns/subscription/keep) |
| Emits | [`CreditGrant.issued`](/business/events/CreditGrant.issued) | By [CreditGrant.issue](/business/nouns/credit-grant/issue) |
| Emits | [`Dispute.accepted`](/business/events/Dispute.accepted) | By [Dispute.accept](/business/nouns/dispute/accept) |
| Emits | [`Dispute.appealed`](/business/events/Dispute.appealed) | By [Dispute.appeal](/business/nouns/dispute/appeal) |
| Emits | [`Invoice.overdue`](/business/nouns/invoice#invoiceoverdue) | Raised when a date passes |
| Emits | [`Subscription.pastDue`](/business/nouns/subscription#subscriptionpastdue) | Raised on a state change |
| Emits | [`Dispute.opened`](/business/nouns/dispute#disputeopened) | Raised by the rail |
| Consumes | [`Offer.published`](/business/events/Offer.published) | Moves [Price](/business/nouns/price) to `fixed` |
| Consumes | [`Offer.withdrawn`](/business/events/Offer.withdrawn) | Moves [Price](/business/nouns/price) to `retired` |
| Consumes | [`Transaction.settled`](/business/nouns/transaction#transactionsettled) | Acts on it |
| Consumes | [`Transaction.failed`](/business/nouns/transaction#transactionfailed) | Acts on it |

## States
The lifecycle of an [Order](/business/nouns/order):

| State | Meaning | Moves to |
| --- | --- | --- |
| `placed` (first) | The Customer committed, with the Offer Version and price fixed; nothing is charged yet. | `paid` by [Order.pay](/business/nouns/order/pay); `canceled` by [Order.cancel](/business/nouns/order/cancel) |
| `paid` | Its amount is settled and its Entries posted; a Service Order’s work runs in `fulfillment`. | `fulfilled` by [Order.fulfill](/business/nouns/order/fulfill); `closed` by [Order.confirm](/business/nouns/order/confirm); `canceled` by [Order.cancel](/business/nouns/order/cancel); `refunded` by [Order.refund](/business/nouns/order/refund) |
| `fulfilled` | What it bought is granted: Entitlements for software and data, or a shipment for goods. | `closed` by [Order.confirm](/business/nouns/order/confirm); `refunded` by [Order.refund](/business/nouns/order/refund) |
| `closed` | The Customer signed off, which earns the Startup its fee. | `refunded` by [Order.refund](/business/nouns/order/refund) |
| `canceled` | Ended before fulfillment, with any payment returned in full. | None: it ends here. |
| `refunded` | Its payment returned in full, with the reversing Entries posted; a partial refund keeps its state. | None: it ends here. |

Its other Nouns with a lifecycle: [Subscription](/business/nouns/subscription), [Invoice](/business/nouns/invoice), [Offer](/business/nouns/offer), [Price](/business/nouns/price).

## Who operates it
| Part | This System |
| --- | --- |
| Accountable | [Billing Specialist](/agents/finance/billing-specialist) |
| Team | [Finance Team](/agents/finance) |
| Seat | A role agent holds it until a Human is seated. |
| Autonomy | `assist` |
| Also calls its Verbs | [Success Manager](/agents/customer/success-manager) |

## Approvals and limits
| Verb | Rule | Detail |
| --- | --- | --- |
| [Order.pay](/business/nouns/order/pay) | A person says yes first | Waits 1 business hour |
| [Order.refund](/business/nouns/order/refund) | A person says yes first | Waits 1 business hour |
| [Invoice.bill](/business/nouns/invoice/bill) | A person says yes first | Waits 1 business hour |
| [Invoice.collect](/business/nouns/invoice/collect) | A person says yes first | Waits 1 business hour |
| [CreditGrant.void](/business/nouns/credit-grant/void) | A person says yes first | Waits 1 business hour |
| [Dispute.answer](/business/nouns/dispute/answer) | A person says yes first | Waits 1 business hour |
| [Dispute.decide](/business/nouns/dispute/decide) | A person says yes first | Waits 1 business hour |
| [Invoice.void](/business/nouns/invoice/void) | A person says yes first | Waits 1 business hour |
| [Invoice.refund](/business/nouns/invoice/refund) | A person says yes first | Waits 1 business hour |
| [Dispute.accept](/business/nouns/dispute/accept) | A person says yes first | Waits 1 business hour |
| [Dispute.appeal](/business/nouns/dispute/appeal) | A person says yes first | Waits 1 business hour |
| [Order.refund](/business/nouns/order/refund) | Limit for the [Billing Specialist](/agents/finance/billing-specialist) | $100 per call |
| [Invoice.collect](/business/nouns/invoice/collect) | Mandate `dunning` for the [Billing Specialist](/agents/finance/billing-specialist) | Retries unpaid Invoices on the dunning schedule without asking each time. |

## Processes that use it
| Process | How it uses it |
| --- | --- |
| [Pricing](/workflows/processes/pricing) | A Workflow writes [Offer](/business/nouns/offer) |
| [Delivery](/workflows/processes/delivery) | A step calls [Invoice.bill](/business/nouns/invoice/bill) |
| [Billing](/workflows/processes/billing) | A step calls [Invoice.collect](/business/nouns/invoice/collect) |
| [Screening](/workflows/processes/screening) | A Workflow writes [Offer](/business/nouns/offer) |
| [Vendor onboarding](/workflows/processes/vendor-onboarding) | A step calls [Invoice.bill](/business/nouns/invoice/bill) |
| [Launches](/workflows/processes/launches) | A Workflow writes [Offer](/business/nouns/offer) |
| [Trials and plan changes](/workflows/processes/plan-changes) | A step calls [Invoice.collect](/business/nouns/invoice/collect) |

## Rail underneath
Stripe’s products (Stripe’s names): **Billing**, **Checkout**, **Invoicing**, **Payments**, **Connect**.

| Noun | Stripe object | Source of truth |
| --- | --- | --- |
| [Subscription](/business/nouns/subscription) | **Subscription** (`subscription`) | The source of truth is db.sb, and Stripe holds a copy written from it. |
| [Invoice](/business/nouns/invoice) | **Invoice** (`invoice`) | The source of truth is db.sb, and Stripe holds a copy written from it. |
| [Dispute](/business/nouns/dispute) | **Dispute** (`dispute`), when `kind` is `chargeback` | The source of truth is Stripe: db.sb mirrors it, written only from Stripe’s webhooks. |
| [Offer](/business/nouns/offer) | **Product** (`product`) | The source of truth is db.sb, and Stripe holds a copy written from it. |
| [Price](/business/nouns/price) | **Price** (`price`) | The source of truth is db.sb, and Stripe holds a copy written from it. |

## Views and dashboards
| View | Shows | Metrics |
| --- | --- | --- |
| Revenue | Paying Customers, outside revenue, and every Invoice past due. | [Outside revenue](/agents/founding#outside-revenue), [Outside paying Customers](/agents/founding#outside-paying-customers), [Net revenue retention](/agents/customer#net-revenue-retention) |
| The [Billing Specialist](/agents/finance/billing-specialist)’s view | The Metrics its accountable Role answers for. | [Days sales outstanding](/agents/finance#days-sales-outstanding) |

## Access
What each Access level may call here.

| Access level | May call |
| --- | --- |
| `owner` | Every Verb (63) |
| `admin` | All but 11 of 63: `CreditGrant.void`, `Dispute.accept`, `Dispute.answer`, `Dispute.appeal`, `Dispute.decide`, `Invoice.bill`, … |
| `member` | All but 11 of 63: `CreditGrant.void`, `Dispute.accept`, `Dispute.answer`, `Dispute.appeal`, `Dispute.decide`, `Invoice.bill`, … |
| `viewer` | Read only (20 of 63) |

## Import and export
None.

## Fees and pricing
Each charge carries one platform fee, withheld before the money reaches the balance; it covers Stripe’s processing cost and the platform’s share, booked as two Entries.

## Availability and limits
| Part | This System |
| --- | --- |
| Status | Live |
| Limit | Charges wait until the Startup finishes Stripe onboarding. |

## Compliance notes
Stripe holds every card number, so card data never reaches db.sb; the Offers and their terms stay the founder’s.

Controls it carries:

- [Log completeness](/systems/trust-and-governance/controls/log-completeness)
- [Append-only records](/systems/trust-and-governance/controls/append-only-records)
- [Point-in-time recovery](/systems/trust-and-governance/controls/point-in-time-recovery)
- [Processing definitions](/systems/trust-and-governance/controls/processing-definitions)
- [Action completion](/systems/trust-and-governance/controls/action-completion)

## Related Systems
- [Ledger](/systems/ledger)
- [Tax](/systems/tax)
- [CRM](/systems/crm)
- [Commerce](/systems/commerce): also holds [Order](/business/nouns/order)
- [Matchmaking](/systems/matching): also holds [Offer](/business/nouns/offer)

## Example
A [Headless SaaS](/products/templates/headless-saas) that turns PDFs into structured data sells $49 a month for 5,000 pages, then $0.01 a page. A [Meter](/business/nouns/meter) counts each conversion once, and at month end Billing invoices the overage to the saved card. A failed charge starts dunning before any Entitlement lapses.