Record a supplier bill

purchasing_create_bill · Changes data · Markdown

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

From your agent’s balance. A call that fails costs nothing.

Nordstahl's bill NS-2026-1188 for the pans we received came in. The PDF is in our files.

Your agent callspurchasing_create_bill$0.01 a call

The example business is Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. The reply is the one the tool really gives.

With these arguments

{
  "order": "PO-0001",
  "reference": "NS-2026-1188",
  "issue_date": "2026-10-13",
  "file_id": "1f3a5c7e-9b2d-4e6f-8a0c-2e4a6c8e0b1d"
}

What comes back

{
  "bill": {
    "bill_id": "821831f3-e199-42a4-93eb-4b2e7c34cf31",
    "supplier": {
      "supplier_id": 4101,
      "name": "Nordstahl Küchentechnik GmbH"
    },
    "reference": "NS-2026-1188",
    "status": "open",
    "overdue": false,
    "days_overdue": 0,
    "currency": "EUR",
    "issue_date": "2026-10-13",
    "due_date": "2026-11-12",
    "total": "462.50",
    "amount_paid": "0.00",
    "balance": "462.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": "43026061-3202-48a5-b581-90dda62227e2",
    "payments": [],
    "file": {
      "file_id": "1f3a5c7e-9b2d-4e6f-8a0c-2e4a6c8e0b1d",
      "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/1f3a5c7e-9b2d-4e6f-8a0c-2e4a6c8e0b1d?t=eyJmIjoiZThhYTFhOTAtZDQzZC00NDdjLWI4MmQtNDhkZDUzYmQ4ZmEzIiwiZXhwIjoxNzkyNDgxMDUyfQ:1xIhjA:buyPNiWn1dK4UphQubok1doMH1fxa3iQnyiH6nP8KXc",
      "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)"
      }
    ]
  }
}

Use it when

A supplier's invoice arrived and should be paid later.

For a cost already paid, use books_record_expense.
For a bill that comes every month, like rent, use purchasing_save_repeating_bill.

What it does

Record a bill a supplier sent, with their reference (their invoice number; the same reference from the same supplier is refused twice). Either its own lines (supplier and lines: each to its book account, default the supplier's; a sku line to the inventory account), or from an order (order, quantities: "received" (default) or "ordered"): what is not billed yet, at the order's costs. It is due due_date, default the issue date plus the supplier's terms. Attach its PDF from the file store with file_id; reading the PDF is your work. A carrier's or the customs office's bill marks the import VAT it passes on with import_vat on its line. When the account keeps books, it is posted to them.

What comes back

bill: its bill_id, supplier, reference, status, currency, lines, totals, issue and due dates, balance and PDF; with tax_treatment, the VAT the business owes itself (self_assessed_tax). Every reply also carries cost_usd and balance_usd.

Inputs

Name	Type	What it is
`supplier`	integer or string	A supplier_id, or the supplier's name. 1 to 200 characters, at least 1.
`order`	string	The order_id, or the order's number like "PO-0007". 1 to 40 characters.
`quantities`	string	One of: received,ordered. Default: received.
`lines`	array of objects	1 to 200 items.
`lines[].sku`	string	An Inventory item's SKU: received stock comes into Inventory. Its name is the default description. Up to 64 characters.
`lines[].description`	string	What is bought. Lines after the first print smaller, underneath. Up to 2,000 characters.
`lines[].quantity`	number or string	Default 1. Up to 6 decimals. Up to 24 characters.
`lines[].unit_cost`Required	number or string	The cost of one before tax; negative for a credit line (a discount). Up to 24 characters.
`lines[].tax_rate`	number or string	Tax percent on the line, e.g. 19. Default 0. Up to 24 characters.
`lines[].account`	string	The book account the line goes to, e.g. "6600". Default: the supplier's. A sku line goes to the inventory account. Up to 20 characters.
`lines[].tracking`	object	With books: tracking options, e.g. {"Department": "Warehouse"}.
`lines[].import_vat`	boolean	The line is import VAT from the customs notice, passed on by the carrier or billed by the customs office: unit_cost is the VAT itself, reclaimed whole (Germany's box 62, the UK's box 4), never a cost. No sku, account, tax_rate or tracking.
`currency`	string	ISO 4217, e.g. "EUR". Default: the supplier's. Matches ^[A-Za-z]{3}$.
`reference`	string	Up to 60 characters.
`issue_date`	string	YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
`due_date`	string	YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
`account`	string	With order: the book account for its lines without a SKU. Default: the supplier's. Up to 20 characters.
`file_id`	string	A file_id from the file store. Exactly 36 characters.
`notes`	string	Up to 5,000 characters.
`tax_treatment`	string	reverse_charge: the supplier's invoice has no VAT because the business owes it (services from abroad, a reverse-charge trade at home); eu_goods: goods bought from another EU country. The lines' tax_rate is the rate owed; the VAT is owed and reclaimed at once. One of: ,reverse_charge,eu_goods.

The call

Over MCP, call purchasing_create_bill on https://api.conecto.chat/mcp/purchasing. Over REST:

Terminal

curl -X POST https://api.conecto.chat/v1/tools/purchasing_create_bill \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order":"PO-0001","reference":"NS-2026-1188","issue_date":"2026-10-13","file_id":"1f3a5c7e-9b2d-4e6f-8a0c-2e4a6c8e0b1d"}'

When it refuses

A refused call costs nothing and says what to do next.

Code	When	What to do
`not_found`404	No purchase order has that order_id or number.	Find it with purchasing_list_orders.
`not_found`404	No supplier of the business has that supplier_id or name.	Call purchasing_list_suppliers, or add the supplier with purchasing_save_supplier.
`not_found`404	A line's SKU is not an Inventory item, or the location does not exist.	Add the item with inventory_save_items, or leave the SKU out.
`archived`409	The supplier, item, location or account is archived.	Bring the supplier back with purchasing_save_supplier archived: false, or use another one.
`invalid_input`400	A date or currency is not valid.	Send dates like 2026-11-02 and currencies like EUR.
`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.
`invalid_input`400	eu_goods for a supplier not known to be in another EU country.	Set the supplier's country, or their VAT ID as tax_id, with purchasing_save_supplier.
`invalid_input`400	An import_vat line has a sku, account, tax_rate or tracking, or sits on a bill with a tax_treatment.	Give the import VAT as a line of its own, on the carrier's or the customs office's bill.
`duplicate`409	A bill from that supplier with that reference is recorded already.	Use the bill the message names.
`not_sent`409	The order is still a draft.	Bills come from orders that were sent.
`order_closed`409	The order is closed.	Draft a new order.
`order_cancelled`409	The order is cancelled.	Draft a new order.
`nothing_to_bill`409	Everything on the order is billed already.	Bill what was ordered with quantities: "ordered".
`no_account`409	A line has no expense or asset account.	Give the line an account, or set the supplier's default account.

More Purchasing tools

All 25 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md

Record a supplier bill

An example

Use it when

What it does

What comes back

Inputs

The call

When it refuses

More Purchasing tools

Give this to your agent.