Overview

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.

How it works

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.

API Endpoints

Method	Endpoint	Description
`GET`	`/bills`	List bills
`POST`	`/bills`	Create bill
`GET`	`/bills/{id}`	Get bill
`PUT`	`/bills/{id}`	Update bill
`DELETE`	`/bills/{id}`	Delete bill
`POST`	`/bills/{id}/finalize`	Finalize bill
`POST`	`/bills/{id}/mark-as-paid`	Mark bill as paid
`GET`	`/bills/export`	Export bills

Important Behaviors

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.

Bill workflow

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

Bill object

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