Invoices
How invoices are modeled and their lifecycle.
An invoice is the core record in VerseBill. It captures who is being billed, what is being charged, and where payment should be sent. Each invoice is identified by a public ID used in the payment link and a human-friendly invoice number scoped to the merchant.
What an invoice contains
- Customer name and optional email
- Line items (description, quantity, unit price) in VERSE
- Total amount, stored in base units (token decimals)
- Recipient wallet address (the merchant's payment address)
- Token contract and chain ID (locked to the trusted VERSE contract)
- Due date and optional notes
Status lifecycle
Invoices start as DRAFT, become PENDING when published, move to PROCESSING while a payment is being verified, and then reach a terminal state: PAID, UNDERPAID, OVERPAID, EXPIRED, or CANCELLED. Transitions are enforced server-side — an invoice can never jump straight from DRAFT to PAID.
Cancelled and expired invoices are hidden from lists and their payment links return 404, so a cancelled invoice can no longer accept funds.