> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.papertracc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server.

# Overview

Bill endpoints mounted at `/bills`.

## Quantities and units

`quantity` on a line item accepts fractional values, and a line can carry a `unit`. What is accepted depends on whether the line is tied to an inventory item through `sku`.

| Line                                                               | `quantity`                                                               | `unit`                                               |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------- |
| No `sku`, or an item with no selling unit                          | Any value above zero, to 4 decimal places.                               | The label you send. Optional, at most 50 characters. |
| `sku` of an item, with `unit` omitted or equal to its selling unit | Whole numbers only for items sold `EACH`, otherwise to 4 decimal places. | The item's selling unit.                             |
| `sku` of an item, with a different `unit`                          | Any value above zero, to 4 decimal places.                               | Kept as sent, for example `CARTON`.                  |

Selling units are `EACH`, `G`, `KG`, `OZ`, `LB`, `ML`, `L`, `FL_OZ`, `CM`, `M`, `IN`, `FT` and `YD`. A `sku` that matches no inventory item is rejected with `404`.

## Billing in a different unit

When a vendor bills in a unit other than the one you stock, send that unit with `unit_factor`, the number of stock units one billed unit holds. `rate` is the price of one billed unit, and `quantity` multiplied by `unit_factor` is the stock quantity the line represents. `unit_factor` is treated as 1 when omitted.

```json
{
  "detail": "Bottled water 75cl",
  "currency_code": "NGN",
  "sku": "SKU-1001",
  "quantity": 2,
  "unit": "CARTON",
  "unit_factor": 12,
  "rate": 6000
}
```

This line bills 2 cartons at 6,000.00 each and represents 24 units of stock.

## Line items in responses

Each line item in a bill response returns `quantity` as a number, `unit` and `unit_factor` when the line has them, and the `sku` of the inventory item the line is tied to. `sku` is empty for lines created without one.

Money values come back as decimal strings: `rate`, `amount` and `vat` on line items, and `value` and `amount` on adjustments. Requests send them as numbers.

## Payment terms

A bill falls due either on a fixed `due_date` or on a payment term. Send `payment_term_id` on create or update to apply a term from `/configs/payment-terms`.

| Request           | Result                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `payment_term_id` | The term is applied. It wins when `due_date` is also sent.                                             |
| `due_date` only   | The bill is due on that date and `payment_schedule` is null.                                           |
| Neither           | The vendor's default term is used when it has one. The workspace default term is not applied to bills. |

When a term is applied, the response carries `payment_schedule` with each instalment's due date and amount and any early-payment discount, and `due_date` is the final due date.

On `PATCH /bills/{id}`, `payment_term_id` rebuilds the schedule from that term. A `due_date` different from the current one replaces the term with that fixed date and clears `payment_schedule`. Changing the bill date or the total recalculates the schedule from the term already on the bill.