Bills represent amounts you owe to vendors. They track expenses, vendor payments, and can be exported for accounting purposes. Bills support draft, finalized, and paid states for workflow management.
- Create a bill - Record an expense owed to a vendor
- Review and finalize - Verify details and finalize the bill
- Mark as paid - Record when payment is made to the vendor
- Export for accounting - Download bills for your accounting system
Example: You receive an invoice from a content provider for $5,000. Create a bill in draft, verify the amount matches the invoice, finalize it, and mark as paid when you send payment.
- Soft delete: Bills are soft-deleted, but only draft bills can be deleted.
- Required on update:
period_start and period_end are required on every update.
- Line items replaced: On update, line items are replaced entirely (not merged).
- Status workflow: Bills follow a lifecycle:
draft → finalized → paid. Only draft bills can be edited or deleted.
- Events:
BillCreated and BillDeleted events are fired.
| Status | Description |
|---|
Draft | Bill is being prepared, can still be edited or deleted |
Open | Bill is finalized and locked, ready for payment |
Paid | Payment has been made to the vendor |
| Attribute | Type | Description |
|---|
id | integer | Unique identifier for the bill |
bill_number | string | Bill number (alias for number) |
number | string | Bill number |
status | string | Bill status: Draft, Open, or Paid |
user_id | integer | ID of the vendor (user record) |
user | object | Vendor details (id, first_name, last_name, email). Always included. |
amount_due | number | Amount due |
amount_paid | number | Amount paid |
amount_remaining | number | Remaining amount |
currency | string | Three-letter ISO currency code |
paid | boolean | Whether the bill has been paid |
metadata | object | Key-value pairs for storing additional data |
subtotal | number | Subtotal before tax |
total | number | Total amount |
footer | string | Additional notes/footer |
purchase_order | string | Purchase order reference number (max 20 chars) |
description | string | Bill description |
period_start | string | Billing period start date (YYYY-MM-DD) |
period_end | string | Billing period end date (YYYY-MM-DD) |
line_items | array | Array of line item objects (id, description, quantity, unit_price, total, currency) |
finalized_at | integer | Unix timestamp when finalized |
paid_at | integer | Unix timestamp when paid |
created_at | integer | Unix timestamp of creation |
updated_at | integer | Unix timestamp of last update |
