Bills

Bills represent payable obligations to vendors. They are the Accounts Payable equivalent of Invoices in the Accounts Receivable API.

Endpoints

Method	Path	Description
POST	/bills	Create a bill
GET	/bills	List bills (paginated, filterable)
GET	/bills/{id}	Get bill by ID
PATCH	/bills/{id}	Update bill fields
DELETE	/bills/{id}	Soft-delete a bill
POST	/bills/{id}/submit	Submit bill for approval
POST	/bills/{id}/reject	Reject a bill
POST	/bills/{id}/pay-date	Set or update scheduled pay date
GET	/bills/{id}/document	Get bill attachment download URL
POST	/bills/upload	Upload document with OCR, create bill
POST	/bills/bulk-submit	Submit multiple bills for approval
POST	/bills/bulk-delete	Soft-delete multiple bills

---

Bill Lifecycle

draft -> needs_approval -> processing -> paid
                        -> failed
         needs_approval -> draft (rejected)

Bills start in draft status. They must be submitted for approval (needs_approval) before payment can be initiated. Once a payment is created, the bill transitions to processing, and eventually to paid or failed.

---

Create Bill

POST /bills

Request Body

{
  "vendor_id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "INV-2026-001",
  "issue_date": "2026-04-01",
  "due_date": "2026-05-01",
  "amount": "1500.00",
  "description": "Monthly hosting services",
  "status": "draft",
  "line_items": [
    {
      "name": "Cloud Hosting",
      "description": "AWS monthly fee",
      "unit_type": "service",
      "quantity": 1,
      "unit_price": 1500.00
    }
  ]
}

Field	Type	Required	Description
vendor_id	string (UUID)	Yes	Vendor to associate the bill with
number	string	No	Bill/invoice number
issue_date	string	Yes	Date the bill was issued (YYYY-MM-DD)
due_date	string	Yes	Payment due date (YYYY-MM-DD)
amount	number	Yes	Total bill amount (e.g. 1500.00)
description	string	No	Bill description
status	string	No	"draft" (default) or "needs_approval"
line_items	array	No	Bill line items

Direct-to-approval: Set status to "needs_approval" to skip the draft stage and submit the bill directly for approval in a single API call.

Response (201 Created)

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "vendor_id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "INV-2026-001",
  "issue_date": "2026-04-01",
  "due_date": "2026-05-01",
  "amount": 1500.00,
  "description": "Monthly hosting services",
  "status": "draft",
  "source": "manual",
  "pay_date": null,
  "line_items": [
    {
      "sequence": 1,
      "name": "Cloud Hosting",
      "description": "AWS monthly fee",
      "unit_type": "service",
      "quantity": 1,
      "unit_price": 1500.00,
      "total": 1500.00,
      "tax": 0.00,
      "expense_account_id": ""
    }
  ],
  "vendor_payments": [],
  "last_status": {
    "status": "draft",
    "reason": null,
    "created_at": "2026-04-01T00:00:00Z",
    "user_id": "770e8400-e29b-41d4-a716-446655440000"
  },
  "created_at": "2026-04-01T00:00:00Z",
  "updated_at": "2026-04-01T00:00:00Z"
}

---

List Bills

GET /bills

Query Parameters

Parameter	Type	Description
limit	integer	Items per page (default 100)
after	string	Forward pagination cursor
before	string	Backward pagination cursor
vendor_id	string	Filter by vendor ID
status	string	Filter by status: draft, needs_approval, processing, paid, deleted, failed
bill_number	string	Filter by bill number
source	string	Filter by source: manual, QuickBooks, ocr
include_deleted	boolean	Include soft-deleted bills (default false)

---

Submit Bill for Approval

POST /bills/{id}/submit

Transitions a bill from draft to needs_approval. No request body required.

---

Reject Bill

POST /bills/{id}/reject

Rejects a bill that is in needs_approval status, moving it back to draft.

Request Body

{
  "reason": "Amount does not match PO"
}

---

Set Pay Date

POST /bills/{id}/pay-date

Sets or updates the scheduled payment date for a bill. This is a prerequisite for initiating a vendor payment. If pay_date is null when you try to create a vendor payment, the request will return 422.

Request Body

{
  "pay_date": "2026-04-15"
}

pay_date must be in YYYY-MM-DD format.

---

Upload Bill Document (OCR)

POST /bills/upload

Upload a document (PDF, PNG, JPEG) as base64-encoded content. The system extracts bill data via OCR and creates a bill automatically.

Request Body

{
  "content": "<base64-encoded-file-content>",
  "filename": "invoice.pdf",
  "content_type": "application/pdf"
}

Field	Type	Required	Description
content	string	Yes	Base64-encoded file content
filename	string	Yes	Original filename
content_type	string	Yes	MIME type (application/pdf, image/png, image/jpeg)

Response (201 Created)

{
  "bill_id": "660e8400-e29b-41d4-a716-446655440000",
  "bill_number": "INV-OCR-001",
  "extracted_data": {
    "vendor_name": "Acme Corp",
    "vendor_email": "[e-mail]",
    "invoice_number": "INV-OCR-001",
    "total": 1500.00,
    "issue_date": "2026-04-01",
    "due_date": "2026-05-01",
    "description": "Monthly services",
    "line_items": [
      {
        "name": "Cloud Hosting",
        "description": "AWS monthly fee",
        "quantity": 1,
        "unit_price": 1500.00,
        "total": 1500.00
      }
    ]
  },
  "document_path": "/uploads/invoice.pdf",
  "warnings": []
}

---

Bulk Submit Bills

POST /bills/bulk-submit

Submit multiple bills for approval in a single request.

Request Body

{
  "bill_ids": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440002"
  ]
}

Response (200 OK)

{
  "results": [
    { "bill_id": "660e8400-...-440001", "success": true },
    { "bill_id": "660e8400-...-440002", "success": true }
  ]
}

---

Bulk Delete Bills

POST /bills/bulk-delete

Soft-delete multiple bills in a single request. Same request/response shape as bulk submit.

---

Bill Statuses

Status	Description
draft	Initial state, editable
needs_approval	Submitted for review
processing	Payment in progress
paid	Payment completed
failed	Payment failed
deleted	Soft-deleted

Bill Sources

Source	Description
manual	Created via API or UI
QuickBooks	Synced from QuickBooks
ocr	Created from document upload with OCR extraction