conecto. Get started
Invoices

Record a payment

invoices_record_payment · Changes data · Markdown

Records money received against a sent invoice, or a refund; the invoice becomes partially paid or paid.

$0.01 a call

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

An example

Hotel Elbblick transferred 6,000 euros toward invoice INV-0042 today, reference RE-0042.

Your agent callsinvoices_record_payment$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
{
  "invoice_id": "2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f",
  "amount": "6000.00",
  "method": "bank_transfer",
  "reference": "RE-0042"
}
What comes back
{
  "invoice": {
    "invoice_id": "2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f",
    "kind": "invoice",
    "number": "INV-0042",
    "status": "partially_paid",
    "currency": "EUR",
    "issue_date": "2026-10-14",
    "due_date": "2026-10-28",
    "overdue": false,
    "days_overdue": 0,
    "customer": {
      "contact_id": null,
      "company_id": null,
      "name": "Hotel Elbblick GmbH",
      "email": "lukas.meyer@hotel-elbblick.example",
      "address": "Elbchaussee 120\n22763 Hamburg",
      "tax_id": "",
      "country": null
    },
    "total": "13887.30",
    "total_formatted": "€13,887.30",
    "amount_paid": "6000.00",
    "balance": "7887.30",
    "balance_formatted": "€7,887.30",
    "public_url": "https://cncto.co/i/z0YW4TSWlxT-bnbJvqs3SjStKE0kz4ky",
    "created_at": "2026-10-14T08:00:00+00:00",
    "sent_at": "2026-10-14T08:00:00+00:00",
    "credited": "0.00",
    "items": [
      {
        "description": "Bistro chair, beech\nStackable, for terraces",
        "quantity": "40",
        "unit_price": "320",
        "tax_rate": "19",
        "discount_percent": "10",
        "amount": "12800.00",
        "discount": "1280.00",
        "tax": "2188.80",
        "total": "13708.80"
      },
      {
        "description": "Delivery and setup",
        "quantity": "1",
        "unit_price": "150",
        "tax_rate": "19",
        "discount_percent": "0",
        "amount": "150.00",
        "discount": "0.00",
        "tax": "28.50",
        "total": "178.50"
      }
    ],
    "totals": {
      "subtotal": "12950.00",
      "subtotal_formatted": "€12,950.00",
      "discount": "1280.00",
      "discount_formatted": "€1,280.00",
      "tax": "2217.30",
      "tax_formatted": "€2,217.30",
      "total": "13887.30",
      "total_formatted": "€13,887.30",
      "credited": "0.00",
      "credited_formatted": "€0.00",
      "amount_paid": "6000.00",
      "amount_paid_formatted": "€6,000.00",
      "balance": "7887.30",
      "balance_formatted": "€7,887.30",
      "taxes": [
        {
          "rate": "19",
          "base": "11670.00",
          "amount": "2217.30",
          "amount_formatted": "€2,217.30"
        }
      ]
    },
    "supply": {
      "label": "Date of supply",
      "text": "October 14, 2026",
      "from": "2026-10-14",
      "until": "2026-10-14"
    },
    "tax_exemption": null,
    "tax_note": null,
    "vat_exchange_rate": null,
    "national_vat": null,
    "e_invoice": null,
    "notes": "",
    "payment_link": null,
    "business": {
      "name": "Hansen & Voss GmbH",
      "address": "Billbrookdeich 112\n22113 Hamburg\nGermany",
      "tax_id": "DE123456789",
      "email": "billing@hansenvoss.example",
      "phone": "+49 40 66969 100",
      "logo_file_id": "",
      "footer": "Please pay by bank transfer to Hansen & Voss GmbH\nIBAN DE89 3704 0044 0532 0130 00, BIC COBADEFFXXX",
      "tax_label": "VAT",
      "paper": "a4",
      "country": "DE",
      "legal_notes": "Hansen & Voss GmbH, Amtsgericht Hamburg HRB 123456\nManaging directors: Clara Hansen, Henrik Voss",
      "document_language": ""
    },
    "pdf": {
      "file_id": "8506d546-cf7e-4729-b619-dc28a816ffff",
      "name": "Invoice INV-0042.pdf",
      "content_type": "application/pdf",
      "size": "582 bytes",
      "size_bytes": 582,
      "sha256": "7a628ee1199dd863f0236a61a39b6729a977b4ea18a669e9930a57280cb2326e",
      "created_at": "2026-10-14T08:00:00+00:00",
      "download_url": "https://cncto.co/d/8506d546-cf7e-4729-b619-dc28a816ffff?t=eyJmIjoiODUwNmQ1NDYtY2Y3ZS00NzI5LWI2MTktZGMyOGE4MTZmZmZmIiwiZXhwIjoxNzkyMTYwODk3fQ:1xHMRN:7YBDRvq66SZ823JBQv2T3k_bEHE9Ih69-5tPA-bcuC8",
      "link_expires_in_hours": 24
    },
    "payments": [
      {
        "payment_id": 4101,
        "amount": "6000.00",
        "amount_formatted": "€6,000.00",
        "date": "2026-10-14",
        "method": "bank_transfer",
        "reference": "RE-0042",
        "note": "",
        "recorded_at": "2026-10-14T08:00:00+00:00"
      }
    ],
    "quote_id": null,
    "credit_notes": [],
    "viewed_at": null,
    "accepted_at": null,
    "declined_at": null,
    "paid_at": null,
    "voided_at": null,
    "void_reason": null,
    "last_emailed_at": "2026-10-14T08:00:00+00:00",
    "reminders_sent": 0,
    "history": [
      {
        "at": "2026-10-14T08:00:00+00:00",
        "event": "created",
        "detail": "",
        "by": "key 4101 (Pip)"
      },
      {
        "at": "2026-10-14T08:00:00+00:00",
        "event": "sent",
        "detail": "INV-0042",
        "by": "key 4101 (Pip)"
      }
    ]
  },
  "payment": {
    "payment_id": 4101,
    "amount": "6000.00",
    "amount_formatted": "€6,000.00",
    "date": "2026-10-14",
    "method": "bank_transfer",
    "reference": "RE-0042",
    "note": "",
    "recorded_at": "2026-10-14T08:00:00+00:00"
  }
}

Use it when

A customer paid by transfer, card or cash, or money went back to them.

What it does

Record money received against a sent invoice: amount, date, method and reference. It becomes partially_paid, or paid when nothing is left. A payment can't be more than the balance, unless keep_excess keeps the rest as the customer's credit (an overpayment, like Xero's, for invoices_use_credit); a negative amount records a refund. When the account keeps books, it is posted to them.

What comes back

invoice: the document with its new status, amount paid and balance; payment: the payment as recorded. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
invoice_idRequiredstringThe invoice_id invoices_create returned (quotes and credit notes have one too). Exactly 36 characters.
amountRequirednumber or stringIn the invoice's currency, e.g. "250.00". Negative for a refund. Up to 24 characters.
datestringWhen it was paid. Default today. Matches ^\d{4}-\d{2}-\d{2}$.
methodstringOne of: bank_transfer,card,cash,check,online,other. Default: other.
referencestringe.g. the bank transfer reference or the payment id. Up to 120 characters.
notestringUp to 500 characters.
keep_excessbooleanPaid more than the balance: keep the rest as the customer's credit. Default: false.

The call

Over MCP, call invoices_record_payment on https://api.conecto.chat/mcp/invoices. Over REST:

Terminal
curl -X POST https://api.conecto.chat/v1/tools/invoices_record_payment \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f","amount":"6000.00","method":"bank_transfer","reference":"RE-0042"}'

When it refuses

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

CodeWhenWhat to do
not_found404No quote or invoice of the business has that invoice_id.Find it with invoices_list and use its invoice_id.
not_an_invoice400The id is a quote or a credit note.Turn a quote into an invoice with invoices_convert_quote; a credit note records money back when it is issued.
not_sent409The invoice is still a draft.Send it with invoices_send first.
void409The invoice is void.Payments go on invoices that are not void.
already_paid409The invoice is paid in full.Nothing more can be recorded, except a refund.
more_than_balance409The amount is more than the balance.Record at most the balance, or keep the rest as the customer's credit with keep_excess.
more_than_paid409The refund is more than what was paid.Refund at most what was paid.
invalid_input400The amount is 0 or not a number in the invoice's currency, or the date is in the future.Send an amount like "250.00" and a date that has passed.
no_rate409There is no exchange rate for the invoice's currency on that day.Set a standing rate with books_setup rates.
rates_loading503The day's exchange rates are still loading.Try again in a few minutes.
before_start409The date is before the books start.Use a later date, or set an earlier start with books_setup.
period_locked409The books are locked for that date.Use a later date, or unlock the period with books_lock.
no_role409The books have no account for a role the posting needs.Give an account that role with books_save_accounts.

More Invoices tools

All 24 tools

Give this to your agent.

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