> 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

Reusable payment terms for invoices and bills.

A payment term describes when a document falls due. Define a term once, then apply it to an invoice or bill with `payment_term_id`, or set it as the default on a customer or vendor.

## Term shapes

| Shape                  | How to define it                                         | Example                                                         |
| ---------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
| Single due date        | `net_days` only.                                         | Net 30: the full amount is due 30 days after the document date. |
| Split instalments      | Two or more `instalments`, each with its own `net_days`. | 60% within 15 days and the remaining 40% within 30.             |
| Early-payment discount | A `discount` on either shape.                            | 2% off when the balance is settled within 10 days.              |

`net_days` counts calendar days from the invoice date or bill date, from 0 to 365.

## Instalments

Each instalment has a `type`, a `value` and a `net_days`.

| Type              | `value`                             |
| ----------------- | ----------------------------------- |
| `PERCENTAGE_RATE` | A percentage of the document total. |
| `FLAT_RATE`       | An amount in the document currency. |

* A term has either no instalments or at least two.
* No two instalments can share the same `net_days`. They are stored in order of `net_days`, and the term's own `net_days` becomes that of the last instalment.
* Instalments that are all percentages must add up to 100.
* When percentages and flat amounts are mixed, the percentages cannot exceed 100 and the last instalment takes whatever remains of the document total.

```json
{
  "name": "60/40 split",
  "instalments": [
    { "type": "PERCENTAGE_RATE", "value": 60, "net_days": 15 },
    { "type": "PERCENTAGE_RATE", "value": 40, "net_days": 30 }
  ]
}
```

## Early-payment discount

`discount` gives a percentage or flat amount off when the balance is settled early. Its `net_days` is the last day the discount can be taken and must be earlier than the term's final due date. A percentage discount must be below 100.

```json
{
  "name": "2/10 Net 30",
  "net_days": 30,
  "discount": { "type": "PERCENTAGE_RATE", "value": 2, "net_days": 10 }
}
```

The discount is only given when the document is settled in full inside the window. See the payments and receipts overviews for how it is recorded.

## Which term a document gets

| Document | Order of precedence                                                                                                                                                         |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invoice  | `payment_term_id` on the request, then `due_date` on the request, then the customer's default term, then the workspace default term, then the workspace's default due days. |
| Bill     | `payment_term_id` on the request, then `due_date` on the request, then the vendor's default term.                                                                           |

The workspace default term, the one with `is_default` set, applies to invoices only. Only one term is the default at a time, so making another term the default unsets the previous one.

## Payment schedule on documents

When a term is applied, the invoice or bill returns a `payment_schedule` holding the term as it stood at that moment, with every due date and amount worked out.

```json
{
  "term_id": "c81e7a35-2f4d-4b6c-9a0e-5d3b7f1c8e92",
  "name": "60/40 split",
  "net_days": 30,
  "instalments": [
    { "type": "PERCENTAGE_RATE", "value": "60", "net_days": 15, "due_date": "2026-07-03T10:00:00Z", "amount": "150000.00" },
    { "type": "PERCENTAGE_RATE", "value": "40", "net_days": 30, "due_date": "2026-07-18T10:00:00Z", "amount": "100000.00" }
  ],
  "discount": null
}
```

* `due_date` on the document is the final due date, the last instalment's date for a split term.
* `instalments` is empty for a single due date.
* Percentage amounts are rounded to two decimal places and the last instalment absorbs the rounding difference.
* Payments are applied to instalments in order, earliest first. An invoice's `is_overdue` is true once any instalment is past its due date and not fully covered by `total_paid`.
* `payment_schedule` is null on documents with a plain due date.

The schedule is a snapshot. Editing or deactivating a term later does not change documents that already use it. When the document's date or total changes, the schedule is recalculated from the term captured on the document.

## Retiring a term

There is no delete endpoint. Set `is_active` to false to retire a term: it can no longer be applied to new documents, it stops being the workspace default, and a customer or vendor that still points to it falls back to the next rule in the precedence order.