How to track reimbursable project expenses and include them on a client invoice

Reimbursable costs are only simple when the rule is written down first: this client pays for assets bought for their project, this licence is shared across clients and stays with the business, travel is rebilled at cost, meals are not. Once the invoice exists, that decision is already made for you.

The rule maps onto billable and non-billable. A billable expense with a client attached is a cost waiting to be rebilled. A non-billable expense is a cost the business absorbs. A billable expense with no client sits in between: Billr cannot put it on a client invoice, so list_unbilled reports it as unassigned work rather than pretending it belongs to somebody.

That is the whole reason to record costs in the invoicing tool rather than a parallel spreadsheet. The spreadsheet and the invoice drift; a single record cannot.

log_expense takes a request_id, a description, an amount, an optional date, a category and, when the cost is reimbursable, the client. Attaching the client is what makes the expense billable by default. Omit the client and billable defaults to false, so the cost is absorbed unless you explicitly pass billable: true.

Categories are a fixed list rather than free text: office, travel, meals, supplies, utilities, software, marketing, professional, insurance, mileage and other. Pick the closest one; the point is that a later review can find costs by kind. The track a billable expense guide covers the same call with the client added by id.

log_expense  {
  "request_id": "4d7a2e69-8b31-4c05-9f82-3a6d1c7b4e58",
  "client_name": "Harbor & Lane",
  "description": "Client-specific stock imagery licence",
  "amount": 180,
  "category": "software",
  "date": "2026-09-11"
}

Expenses split by billability

Billr demo data, fictional throughout. View full size

• Shared tooling that serves every client belongs in the absorbed column, not in one client invoice.
• A cost logged without a client is absorbed already, because billable defaults to false in that case. Nothing further is needed.
• If a cost starts as billable and turns out not to be, update_expense with billable: false removes it from the unbilled list before it reaches an invoice.
• If a cost was logged without a client and should be rebilled, update_expense can attach the client and mark it billable in the same call. If it is already marked billable but still has no client, it remains unassigned.

update_expense  {
  "expense_id": "a7d4e1b8-3c69-4f25-8e40-9b6a2d5c1f38",
  "billable": false
}
update_expense  {
  "expense_id": "e6a2d9c4-1f58-4b73-9c26-8d3a5e1b7f40",
  "client_id": "9f2a4d18-3b7c-4a6e-8f0d-1c5b2e9a7d44",
  "billable": true
}

Two reads answer the question. list_unbilled shows the costs that are billable, unbilled and attached to a client, grouped with the time for that client. list_expenses shows the full picture, including what has already been billed and what is being absorbed, with billed accepting billed, unbilled or all.

A cost missing from list_unbilled is not automatically an absorbed cost. There are four ordinary reasons it can be absent: it is non-billable, it is already attached to an invoice, your read was filtered or paged past it, or it is billable with no client and therefore reported in the unassigned section instead of a client group. Check which one applies before you conclude anything.

Pagination is the easy one to miss: both tools return next_offset when there is more to read, so a short list can simply mean you stopped early. The find unbilled work before you invoice guide walks the same grouping, and keeping costs separate covers what belongs on the business side.

list_unbilled  { "client_id": "9f2a4d18-3b7c-4a6e-8f0d-1c5b2e9a7d44" }
list_expenses  { "client_name": "Harbor & Lane", "billed": "unbilled", "from": "2026-09-01", "to": "2026-09-30" }

Pass the expense ids to create_invoice along with any time you are billing for the same client. The source costs are priced onto the invoice, written as line items, and attached in the same atomic step, which is what stops a second invoice from claiming them later.

Costs are rebilled at the amount you recorded. There is no automatic markup, so if your agreement includes a handling fee, add it as its own line_items entry with a description that explains it. Mixed invoices are fine: linked source work and hand-written lines can share one draft.

create_invoice  {
  "request_id": "7f1c4a96-2e53-4b08-9d71-6a3e5c2b8f14",
  "client_name": "Harbor & Lane",
  "time_entry_ids": ["3f6c1a44-5b2d-4e71-9c08-7a1d3f5b9e22"],
  "expense_ids": ["b1e5c7a2-4d96-4f30-8a17-6c2b9e4d1f73", "e6a2d9c4-1f58-4b73-9c26-8d3a5e1b7f40"],
  "line_items": [
    {
      "description": "Expense handling fee",
      "quantity": 1,
      "rate": 25
    }
  ]
}

{
  "summary": "Drafted INV-1154 for Harbor & Lane: $901.50",
  "invoice": {
    "invoice_number": "INV-1154",
    "status": "draft",
    "currency": "USD",
    "subtotal": 901.5,
    "total": 901.5,
    "balance_due": 901.5
  },
  "linked_time_entry_ids": [
    "3f6c1a44-5b2d-4e71-9c08-7a1d3f5b9e22"
  ],
  "linked_expense_ids": [
    "b1e5c7a2-4d96-4f30-8a17-6c2b9e4d1f73",
    "e6a2d9c4-1f58-4b73-9c26-8d3a5e1b7f40"
  ]
}

• Expenses are stored with their own currency and grouped per currency. A USD cost cannot be dropped onto a EUR invoice.
• Amounts are flat figures with no unit conversion, so mileage is recorded as the amount you are charging, not as a distance.
• Amounts must be greater than zero. There is no negative expense and no credit-note line, so a refund or a reversed cost is handled with a correction rather than a minus sign.
• Receipt files are not uploaded to Billr. Keep the paper trail wherever your accounting lives and use the notes field to describe where it is.
• Non-billable is not the same as invisible: an absorbed cost still appears in list_expenses, which is what makes a profitability review possible later.