pay_invoice
Record a payment against an invoice or bill from your bank account, handling partial payments, currency exchange gains/losses, and early-payment discounts.
Instructions
Record a payment against a posted invoice or bill.
Creates a payment transaction from the specified bank/cash account to the invoice's A/R or A/P account. Partial payments are supported.
For cross-currency payments where the rate moved between
post-date and pay-date, a realized FX gain/loss split is
booked. Pass fx_account to control routing; otherwise
the server picks the unique INCOME/EXPENSE account whose
leaf name matches "fx", "forex", "foreign exchange",
"currency gain/loss", "exchange gain/loss", or "currency
translation". When zero or multiple match, the canonical
Income:Foreign Exchange Gain/Loss is used (auto-created
if absent), and an fx_notice is returned listing
ambiguous candidates so you can pass fx_account
explicitly next time.
For invoices with early-payment-discount terms (e.g.,
"2/10 Net 30" = 2% off if paid within 10 days), pass
apply_discount=True to settle via discount. The tool
validates that the invoice has discount terms, the payment
date is within the discount window, and the shortfall
matches the expected discount on pre-tax principal. Each
failure mode rejects with a specific error rather than
silently downgrading to a partial payment. discount_account
controls routing the same way fx_account does
(auto-resolves to Expenses:Sales Discounts for customer
payments, Income:Purchase Discounts Taken for vendor
bill payments).
Args:
id: Invoice or bill ID (e.g., "000001").
payment_account: Bank or cash account for payment (e.g., "Assets:Checking").
amount: Payment amount as decimal string (e.g., "500.00").
payment_date: Payment date (YYYY-MM-DD). Defaults to today.
description: Description for the payment transaction. Optional.
owner_type: "customer" or "vendor" for disambiguation.
fx_account: Optional INCOME or EXPENSE account to receive
realized FX gain/loss (cross-currency payments only).
Accepts a full path, %short GUID, or full 32-char GUID.
apply_discount: When True, treat this payment as the
final settlement and absorb the early-payment
discount from the invoice's billterm. Default False
— explicit opt-in. Hard-rejects on credit notes
(refunds don't take discounts).
discount_account: Optional INCOME or EXPENSE account to
receive the discount split. Auto-resolves when
omitted. Accepts full path, %short GUID, or full
32-char GUID.
force: Override the stale-FX-rate guard. A cross-currency
payment etches the rate at pay time; if the latest
price is 7–90 days from the payment date the payment
is refused with stale_fx_rate unless force=True
(the override is recorded as fx_stale/"forced").
A rate beyond the 90-day cap cannot be forced.
memo: Optional memo for the bank-account split (e.g.,
check number or wire reference). description
names the whole transaction; memo annotates the
cash movement.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| memo | No | ||
| force | No | ||
| amount | Yes | ||
| fx_account | No | ||
| owner_type | No | ||
| description | No | ||
| payment_date | No | ||
| apply_discount | No | ||
| payment_account | Yes | ||
| discount_account | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |