--- name: "purchasing_pay_bill" area: "purchasing" title: "Record a bill payment" price: "$0.01" method: "POST" url: "https://api.conecto.chat/v1/tools/purchasing_pay_bill" mcp_server: "https://api.conecto.chat/mcp/purchasing" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/purchasing/purchasing_pay_bill" --- # Record a bill payment (`purchasing_pay_bill`) Records money paid on a bill, or money back from the supplier; it is posted to the books. Record money paid on a bill: amount (at most the balance, unless keep_excess keeps the rest as a credit with the supplier for purchasing_use_credit), date, method and reference. It becomes partially_paid, or paid when nothing is left. A negative amount records money back from the supplier. When the account keeps books, the payment is posted (accounts payable against the bank, with any exchange difference). books_match_bank_lines can do this from a bank line too. Price: $0.01 a call. A call that fails costs nothing. ## Use it when The business paid a supplier, in full or in part. ## Say this to your agent > We paid 400 euros of Nordstahl's bill by bank transfer this morning. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `bill_id` | string | yes | The bill_id purchasing_create_bill returned. Exactly 36 characters. | | | | `amount` | number or string | yes | In the bill's currency, e.g. "250.00". Negative for a refund. Up to 24 characters. | | | | `date` | string | no | When it was paid. Default today. Matches ^\\d{4}-\\d{2}-\\d{2}$. | | | | `method` | string | no | | `"bank_transfer"`, `"card"`, `"cash"`, `"check"`, `"online"`, `"other"` | `"bank_transfer"` | | `reference` | string | no | Up to 120 characters. | | | | `note` | string | no | Up to 500 characters. | | | | `keep_excess` | boolean | no | Paid more than the balance: keep the rest as a credit with the supplier. | | `false` | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `purchasing_pay_bill` on the MCP server `https://api.conecto.chat/mcp/purchasing` with these arguments: ```json { "bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b", "amount": "400.00", "method": "bank_transfer", "reference": "NS-2026-1188" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/purchasing_pay_bill \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b", "amount": "400.00", "method": "bank_transfer", "reference": "NS-2026-1188"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "purchasing_pay_bill", "status": "succeeded", "replayed": false, "cost_usd": "$0.01", "balance_usd": "$19.75", "result": { "bill": { "bill_id": "3c5e7a9b-1d2f-4a6c-8e0b-4d6f8a1c3e5b", "supplier": { "supplier_id": 4101, "name": "Nordstahl Küchentechnik GmbH" }, "reference": "NS-2026-1188", "status": "partially_paid", "overdue": false, "days_overdue": 0, "currency": "EUR", "issue_date": "2026-10-13", "due_date": "2026-11-12", "total": "462.50", "amount_paid": "400.00", "balance": "62.50", "order": "PO-0001", "lines": [ { "description": "GN 1/1 pan, steel, 65 mm", "sku": "GN-PAN-11", "account": null, "quantity": "25", "unit_cost": "18.5", "tax_rate": "0", "amount": "462.50", "tax": "0.00", "order_line": 1 } ], "subtotal": "462.50", "tax": "0.00", "tax_treatment": null, "order_id": "c28af832-d83d-49d8-bd56-3dd753be6569", "payments": [ { "payment_id": 4101, "amount": "400.00", "date": "2026-10-14", "method": "bank_transfer", "reference": "NS-2026-1188", "note": null, "batch": null } ], "file": { "file_id": "605f22af-76c5-4b1f-8222-3366c2016b74", "name": "NS-2026-1188.pdf", "content_type": "application/pdf", "size": "1.1 KB", "size_bytes": 1147, "sha256": "24cfafaca922f96f27862a78624077499c6933a1caf04ba986e83cc228a836c3", "created_at": "2026-10-14T08:00:00+00:00", "download_url": "https://cncto.co/d/605f22af-76c5-4b1f-8222-3366c2016b74?t=eyJmIjoiNjA1ZjIyYWYtNzZjNS00YjFmLTgyMjItMzM2NmMyMDE2Yjc0IiwiZXhwIjoxNzkyNDgxMDUzfQ:1xIhjB:FjPchhI8gZZUqY3imHyJzDWd1mB72vxd-1hxTklLetg", "link_expires_in_hours": 24 }, "notes": null, "books_entry": 1, "void_reason": null, "history": [ { "at": "2026-10-14T08:00:00+00:00", "event": "recorded", "detail": "Pip", "by": "key 4101 (Pip)" }, { "at": "2026-10-14T08:00:00+00:00", "event": "payment", "detail": "€400.00", "by": "key 4101 (Pip)" } ] }, "payment": { "payment_id": 4101, "amount": "400.00", "date": "2026-10-14", "method": "bank_transfer" } } } ``` `result`: bill: the bill with its new status, amount paid and balance; payment: the payment as recorded. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No bill of the business has that bill_id. | Find it with purchasing_list_bills. | | `unbalanced` | 400 | The debits and credits do not add up to the same amount. | Make the lines balance. | | `before_start` | 409 | The date is before the books start. | Use a later date. | | `period_locked` | 409 | The books are locked for that date. | Use a later date, or unlock with books_lock. | | `no_rate` | 409 | There is no exchange rate for the currency on that day. | Pass rate, or set a standing rate with books_setup rates. | | `rates_loading` | 503 | The day's exchange rates are still loading. | Try again in a few minutes, or pass rate. | | `void` | 409 | The bill is void. | Payments go on bills that are not void. | | `already_paid` | 409 | The bill is paid in full. | Nothing more can be paid, except money back. | | `more_than_balance` | 409 | The amount is more than the balance. | Pay at most the balance, or keep the rest as a credit with the supplier with keep_excess. | | `more_than_paid` | 409 | The money back is more than what was paid. | Record at most what was paid. | | `invalid_input` | 400 | The amount is not a number, or the date is not valid. | Send an amount like "400.00". | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [purchasing_save_supplier](https://conecto.chat/tools/purchasing/purchasing_save_supplier.md): Adds a supplier or changes one: contact, email for orders, address, currency, payment terms and the book account their bills go to. $0.01 a call. - [purchasing_list_suppliers](https://conecto.chat/tools/purchasing/purchasing_list_suppliers.md): Suppliers by name, each with what is owed to them on open bills and how many orders are open. Free up to 1,000,000 reads a month. - [purchasing_save_supplier_items](https://conecto.chat/tools/purchasing/purchasing_save_supplier_items.md): Says which Inventory items a supplier sells: their code, cost, pack size, minimum order, lead time and a fixed reorder quantity. $0.005 per item saved. - [purchasing_list_supplier_items](https://conecto.chat/tools/purchasing/purchasing_list_supplier_items.md): What suppliers sell: codes, costs, packs, minimums, lead times and the preferred supplier, for one supplier or one SKU. Free up to 1,000,000 reads a month. - [purchasing_draft_reorders](https://conecto.chat/tools/purchasing/purchasing_draft_reorders.md): Drafts one purchase order per supplier for every item at or below its reorder point, counting what is already on order. $0.01 per draft order. - [purchasing_create_order](https://conecto.chat/tools/purchasing/purchasing_create_order.md): Drafts a purchase order to a supplier: lines (with Inventory SKUs if you like), currency, delivery date and stock location. $0.01 a call. - [purchasing_update_order](https://conecto.chat/tools/purchasing/purchasing_update_order.md): Changes a draft order, or records it as sent without emailing it. $0.01 a call. - [purchasing_send_order](https://conecto.chat/tools/purchasing/purchasing_send_order.md): Emails an order to the supplier with a link to its PDF; a draft takes the next number first. $0.10 a call. - [purchasing_receive](https://conecto.chat/tools/purchasing/purchasing_receive.md): Records what arrived on a sent order; lines with a SKU come into Inventory at the ordered cost. $0.01 a call. - [purchasing_close_order](https://conecto.chat/tools/purchasing/purchasing_close_order.md): Closes a sent order (stop waiting for the rest) or cancels one that received nothing. $0.01 a call. - [purchasing_list_orders](https://conecto.chat/tools/purchasing/purchasing_list_orders.md): Purchase orders, newest first, by status, supplier or date; or one order in full. Free up to 1,000,000 reads a month. - [purchasing_create_bill](https://conecto.chat/tools/purchasing/purchasing_create_bill.md): Records a bill a supplier sent, from its own lines or from an order, with its PDF; it is posted to the books. $0.01 a call. - [purchasing_update_bill](https://conecto.chat/tools/purchasing/purchasing_update_bill.md): Adds a recorded bill's PDF if it has none, or changes its notes or due date; amounts and the PDF it has never change. $0.01 a call. - [purchasing_pay_bills](https://conecto.chat/tools/purchasing/purchasing_pay_bills.md): Pays several bills at once from one bank account, like Xero's batch payments, with the SEPA file to upload to the bank. $0.01 per bill paid. - [purchasing_set_planned_date](https://conecto.chat/tools/purchasing/purchasing_set_planned_date.md): Plans the day the business will pay a bill, so the cash flow forecast takes the money out then rather than on the due date. Free. - [purchasing_record_prepayment](https://conecto.chat/tools/purchasing/purchasing_record_prepayment.md): Records a deposit the business paid a supplier before their bill, like Xero's prepayments; it waits as a credit with them. $0.01 a call. - [purchasing_use_credit](https://conecto.chat/tools/purchasing/purchasing_use_credit.md): Puts a credit with a supplier on their bill, like Xero's allocate credit, or records it coming back. $0.01 a call. - [purchasing_list_credits](https://conecto.chat/tools/purchasing/purchasing_list_credits.md): Lists credits with suppliers, deposits and overpayments, with what is left on each. Free up to 1,000,000 reads a month. - [purchasing_save_repeating_bill](https://conecto.chat/tools/purchasing/purchasing_save_repeating_bill.md): Records a supplier's bill again every so many weeks, months or years, with [Month] and [Year] filled in, like Xero's repeating bills. $0.01 a call. - [purchasing_list_repeating_bills](https://conecto.chat/tools/purchasing/purchasing_list_repeating_bills.md): Lists the repeating bills: whose each is, how often, the next dates, and what each recorded. Free up to 1,000,000 reads a month. - [purchasing_delete_repeating_bill](https://conecto.chat/tools/purchasing/purchasing_delete_repeating_bill.md): Stops a repeating bill for good; the bills it recorded stay. Free. - [purchasing_void_bill](https://conecto.chat/tools/purchasing/purchasing_void_bill.md): Voids a bill entered by mistake; the books reverse it and its order can be billed again. $0.01 a call. - [purchasing_list_bills](https://conecto.chat/tools/purchasing/purchasing_list_bills.md): Supplier bills by due date, filtered by status, supplier, order or dates; or one bill in full. Free up to 1,000,000 reads a month. - [purchasing_report](https://conecto.chat/tools/purchasing/purchasing_report.md): Aged payables (what is owed to each supplier by how late) or spend (what each supplier billed and was paid). Free up to 1,000,000 reads a month.