Invoice · StartupBuilder

Properties

Property	Type	Required	Description
`total`	`money`	required	The amount due.
`due`	`date`	required	When payment is due.
`paidAt`	`datetime`		When it was paid.
`status`	`string`		One of `draft`, `open`, `paid`, `void`, or `uncollectible`.
`collection`	`string`		`charge` charges the saved payment method; `send` sends the Invoice and waits for a transfer. `charge` by default.
`terms`	`integer`		Days from issue until a `send` Invoice is due, such as 30; sets `due`.
`purchaseOrder`	`string`		The Customer’s purchase order number, printed on the Invoice.
`refunded`	`money`		The total returned to the Customer, from zero up to the amount paid.
`number`	`string`		The Invoice number, sequential per Startup and never reused, voided Invoices included.
`lines`	`json`		Each Offer billed: its quantity, Period and amount, with any Coupon or Credit Grant applied.
`pdf`	`url`		The Invoice, or its receipt once paid, as a PDF on the Startup’s Domain that names the seller of record.
`payUrl`	`url`		The page on the Startup’s Domain where the Customer pays it by card or bank transfer.

Object

JSON

{
  "$id": "https://api.sb/patentpad.com/invoices/invoice_1",
  "$type": "Invoice",
  "total": {
    "amount": 499,
    "currency": "USD"
  },
  "due": "2026-10-22",
  "paidAt": "2026-10-22T12:00:00Z",
  "status": "draft",
  "collection": "charge",
  "terms": 1,
  "purchaseOrder": "PO-48213",
  "refunded": {
    "amount": 499,
    "currency": "USD"
  },
  "number": "LEDG-0042",
  "lines": {},
  "pdf": "https://patentpad.com",
  "payUrl": "https://patentpad.com"
}

Relationships

An Invoice is billed for one Subscription: the Invoices the Subscription issues, one for each period it renews. billedFor, inverse bills.
An Invoice charges one Customer: each Invoice is owed by one Customer. charges, inverse invoices.
An Invoice has many Credit Grants: the Invoices the grant paid toward when they finalized. creditGrants, inverse offsets.

Lifecycle

State	Meaning	Moves to
`draft` (first)	Its lines can still change, and the Customer has not seen it.	`open` by Invoice.bill; `void` by Invoice.void
`open`	Finalized and presented to the Customer, its lines frozen.	`paid` by Invoice.collect; `void` by Invoice.void; `uncollectible` on `Invoice.overdue` when every retry on the Startup’s retry schedule has failed
`paid`	Paid in full; a refund adds to its refunded total and never reopens it.	None: it ends here.
`void`	Canceled unpaid and kept on record, with its reversing Entries posted.	None: it ends here.
`uncollectible`	Kept on record as unpaid once every retry has failed.	None: it ends here.

Verbs

createCreates an Invoice.
POST /{namespace}/invoicesdoInvoice.created
getReturns one Invoice by id.
GET /{namespace}/invoices/{id}readNo Event
listReturns Invoices, newest first, one page at a time.
GET /{namespace}/invoicesreadNo Event
updateChanges the given properties of an Invoice.
PATCH /{namespace}/invoices/{id}doInvoice.updated
billBill finalizes an Invoice and presents it to the Customer for payment.
POST /{namespace}/invoices/{invoice}/billdoInvoice.billed
collectCollect charges a Customer’s saved payment method for an open Invoice and retries on failure.
POST /{namespace}/invoices/{invoice}/collectdoInvoice.collected
refundRefund returns all or part of a paid Invoice to the Customer’s original payment method and posts the reversing Entries.
POST /{namespace}/invoices/{invoice}/refunddoInvoice.refunded
voidVoid cancels an unpaid Invoice, keeps it on record, and posts the reversing Entries.
POST /{namespace}/invoices/{invoice}/voiddoInvoice.voided

An Invoice is never deleted: it ends by Invoice.void, and its records stay.

Events

Events no Verb emits. Each Verb’s Event is in the Verbs table above; every Event is delivered in the same shape.

Invoice.overdue

An open Invoice passed its due date unpaid, or a retry on the Startup’s retry schedule failed. Raised by a clock.

Field	Type	Required	Description
`name`	`string`	required	`Invoice.overdue`.
`at`	`datetime`	required	When it happened.
`seq`	`integer`		Its position in the namespace, one more than the Event before; any seq is a cursor into the history.
`data`	`json`	required	The Thing as the Action left it.
`data.invoice`	Invoice	required	The Invoice as the change left it.
`data.invoice.total`	`money`	required	The amount due.
`data.invoice.due`	`date`	required	When payment is due.
`data.invoice.paidAt`	`datetime`		When it was paid.
`data.invoice.status`	`string`		One of `draft`, `open`, `paid`, `void`, or `uncollectible`.
`data.invoice.collection`	`string`		`charge` charges the saved payment method; `send` sends the Invoice and waits for a transfer. `charge` by default.
`data.invoice.terms`	`integer`		Days from issue until a `send` Invoice is due, such as 30; sets `due`.
`data.invoice.purchaseOrder`	`string`		The Customer’s purchase order number, printed on the Invoice.
`data.invoice.refunded`	`money`		The total returned to the Customer, from zero up to the amount paid.
`data.invoice.number`	`string`		The Invoice number, sequential per Startup and never reused, voided Invoices included.
`data.invoice.lines`	`json`		Each Offer billed: its quantity, Period and amount, with any Coupon or Credit Grant applied.
`data.invoice.pdf`	`url`		The Invoice, or its receipt once paid, as a PDF on the Startup’s Domain that names the seller of record.
`data.invoice.payUrl`	`url`		The page on the Startup’s Domain where the Customer pays it by card or bank transfer.
`data.attempt`	`integer`	required	Which retry failed; 0 when the due date passed.
`data.nextRetryAt`	`datetime`		When the next retry runs; empty after the last one.

JSON

{
  "$id": "https://api.sb/patentpad.com/events/event_1",
  "$type": "Event",
  "name": "Invoice.overdue",
  "at": "2026-10-22T12:00:00Z",
  "data": {
    "invoice": {
      "$id": "https://api.sb/patentpad.com/invoices/invoice_1",
      "$type": "Invoice",
      "total": {
        "amount": 499,
        "currency": "USD"
      },
      "due": "2026-10-22",
      "paidAt": "2026-10-22T12:00:00Z",
      "status": "open",
      "collection": "charge",
      "terms": 1,
      "purchaseOrder": "PO-48213",
      "refunded": {
        "amount": 499,
        "currency": "USD"
      },
      "number": "LEDG-0042",
      "lines": {},
      "pdf": "https://patentpad.com",
      "payUrl": "https://patentpad.com"
    },
    "attempt": 1,
    "nextRetryAt": "2026-10-22T12:00:00Z"
  },
  "seq": 1
}

Permissions

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

Operation	`owner`	`admin`	`member`	`viewer`
`Invoice.create`	Yes	Yes	Yes	No
`Invoice.get`	Yes	Yes	Yes	Yes
`Invoice.list`	Yes	Yes	Yes	Yes
`Invoice.update`	Yes	Yes	Yes	No
`Invoice.bill`	Yes	No	No	No
`Invoice.collect`	Yes	No	No	No
`Invoice.refund`	Yes	No	No	No
`Invoice.void`	Yes	No	No	No

Stripe

Invoice (invoice). The source of truth is db.sb, and Stripe holds a copy written from it.

Property	Stripe field	Source of truth
`total`	`total`	db.sb
`due`	`due_date`	db.sb
`status`	`status`	Stripe
`paidAt`	`status_transitions.paid_at`	Stripe
`collection`	`collection_method`	db.sb
`terms`	`days_until_due`	db.sb
`number`	`number`	db.sb
`lines`	`lines.data`	db.sb

State	Stripe status
`draft`	`draft`
`open`	`open`
`paid`	`paid`
`void`	`void`
`uncollectible`	`uncollectible`

Call it

Text

Bill the latest invoice.

Example

The monthly Invoice to a dental group bills $99 for the base plan and $36 for 1,200 reminders over its Limit. It is due in 15 days.

PropertiesCopy Anchor Link

ObjectCopy Anchor Link

RelationshipsCopy Anchor Link

LifecycleCopy Anchor Link

VerbsCopy Anchor Link

EventsCopy Anchor Link

Invoice.overdueCopy Anchor Link

PermissionsCopy Anchor Link

StripeCopy Anchor Link

Call itCopy Anchor Link

ExampleCopy Anchor Link