Billing
Billing turns accepted Offers into Orders, Subscriptions, Invoices, metered usage and Entitlements on Stripe, with checkout and dunning.
Billing charges Customers for accepted Offers: checkout, Subscriptions, Invoices, metered usage and Entitlements, 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, Database, Event streams, Workflows |
Nouns it owns
| Noun | Definition |
|---|---|
| Order | An Order is a Customer’s commitment to buy one or more Offers once, moving from placed to paid, fulfilled, and closed. |
| Subscription | A Subscription is a Customer’s standing acceptance of an Offer, billed each Period until canceled. |
| Invoice | An Invoice is what a Customer owes for one or more Offers over one billing period. |
| Meter | A Meter is a billable measure of usage that turns usage Events into Entries exactly once. |
| 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 | 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 | A Credit Grant is a prepaid or promotional balance a Customer spends on a Startup’s metered Offers, checked before each call. |
| Offer | An Offer is a Product, under a Brand, at a price, on terms, made by a Startup. |
| Price | A Price is the amount, currency, unit, and tiers of an Offer, embedded in it; zero is a Price. |
| 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 | 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
Events
States
The lifecycle of an 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; canceled by Order.cancel |
paid | Its amount is settled and its Entries posted; a Service Order’s work runs in fulfillment. | fulfilled by Order.fulfill; closed by Order.confirm; canceled by Order.cancel; refunded by Order.refund |
fulfilled | What it bought is granted: Entitlements for software and data, or a shipment for goods. | closed by Order.confirm; refunded by Order.refund |
closed | The Customer signed off, which earns the Startup its fee. | refunded by 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, Invoice, Offer, Price.
Who operates it
| Part | This System |
|---|---|
| Accountable | Billing Specialist |
| Team | Finance Team |
| Seat | A role agent holds it until a Human is seated. |
| Autonomy | assist |
| Also calls its Verbs | Success Manager |
Approvals and limits
| Verb | Rule | Detail |
|---|---|---|
| Order.pay | A person says yes first | Waits 1 business hour |
| Order.refund | A person says yes first | Waits 1 business hour |
| Invoice.bill | A person says yes first | Waits 1 business hour |
| Invoice.collect | A person says yes first | Waits 1 business hour |
| CreditGrant.void | A person says yes first | Waits 1 business hour |
| Dispute.answer | A person says yes first | Waits 1 business hour |
| Dispute.decide | A person says yes first | Waits 1 business hour |
| Invoice.void | A person says yes first | Waits 1 business hour |
| Invoice.refund | A person says yes first | Waits 1 business hour |
| Dispute.accept | A person says yes first | Waits 1 business hour |
| Dispute.appeal | A person says yes first | Waits 1 business hour |
| Order.refund | Limit for the Billing Specialist | $100 per call |
| Invoice.collect | Mandate dunning for the Billing Specialist | Retries unpaid Invoices on the dunning schedule without asking each time. |
Processes that use it
| Process | How it uses it |
|---|---|
| Pricing | A Workflow writes Offer |
| Delivery | A step calls Invoice.bill |
| Billing | A step calls Invoice.collect |
| Screening | A Workflow writes Offer |
| Vendor onboarding | A step calls Invoice.bill |
| Launches | A Workflow writes Offer |
| Trials and plan changes | A step calls Invoice.collect |
Rail underneath
Stripe’s products (Stripe’s names): Billing, Checkout, Invoicing, Payments, Connect.
| Noun | Stripe object | Source of truth |
|---|---|---|
| Subscription | Subscription (subscription) | The source of truth is db.sb, and Stripe holds a copy written from it. |
| Invoice | Invoice (invoice) | The source of truth is db.sb, and Stripe holds a copy written from it. |
| Dispute | Dispute (dispute), when kind is chargeback | The source of truth is Stripe: db.sb mirrors it, written only from Stripe’s webhooks. |
| Offer | Product (product) | The source of truth is db.sb, and Stripe holds a copy written from it. |
| 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, Outside paying Customers, Net revenue retention |
| The Billing Specialist’s view | The Metrics its accountable Role answers for. | 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
- Append-only records
- Point-in-time recovery
- Processing definitions
- Action completion
Related Systems
Example
A Headless SaaS that turns PDFs into structured data sells $49 a month for 5,000 pages, then $0.01 a page. A 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.