Create and manage bills for vendor payments and expenses.
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_startandperiod_endare 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:
BillCreatedandBillDeletedevents 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 |