conecto. Get started
Invoices

Use or pay back a credit

invoices_use_credit · Changes data · Markdown

Puts a customer's credit on their invoice, like Xero's allocate credit, or pays it back to them.

$0.01 a call

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

An example

Use Hotel Elbblick's deposit on the dishwasher invoice.

Your agent callsinvoices_use_credit$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
{
  "credit": "CR-0001",
  "invoice_id": "7b1f6d2e-3c4a-4e8f-9a1b-2c3d4e5f6a7b"
}
What comes back
{
  "credit": {
    "number": "CR-0001",
    "kind": "prepayment",
    "status": "used",
    "date": "2026-10-14",
    "currency": "EUR",
    "amount": "3570.00",
    "left": "0.00",
    "tax_rate": "19",
    "tax": "570.00",
    "method": "bank_transfer",
    "reference": "Deposit, dishwasher DW-500",
    "note": null,
    "entry": 1,
    "customer": {
      "name": "Hotel Elbblick GmbH",
      "email": "einkauf@elbblick.example"
    },
    "history": [
      {
        "at": "2026-10-14T08:00:00+00:00",
        "what": "received",
        "amount": "3570.00"
      },
      {
        "at": "2026-10-14T08:00:00+00:00",
        "what": "used",
        "amount": "3570.00",
        "tax": "570.00",
        "payment": 1,
        "invoice": "INV-0042"
      }
    ]
  },
  "invoice": {
    "invoice_id": "7b1f6d2e-3c4a-4e8f-9a1b-2c3d4e5f6a7b",
    "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": "einkauf@elbblick.example",
      "address": "",
      "tax_id": "",
      "country": null
    },
    "total": "11900.00",
    "total_formatted": "€11,900.00",
    "amount_paid": "3570.00",
    "balance": "8330.00",
    "balance_formatted": "€8,330.00",
    "public_url": "https://cncto.co/i/8NB3-K-Y31Ru3-4gHQU4jjFbOZzOEfLz",
    "created_at": "2026-10-14T08:00:00+00:00",
    "sent_at": "2026-10-14T08:00:00+00:00",
    "credited": "0.00",
    "items": [
      {
        "description": "Dishwasher DW-500, hood type",
        "quantity": "1",
        "unit_price": "10000",
        "tax_rate": "19",
        "discount_percent": "0",
        "amount": "10000.00",
        "discount": "0.00",
        "tax": "1900.00",
        "total": "11900.00"
      }
    ],
    "totals": {
      "subtotal": "10000.00",
      "subtotal_formatted": "€10,000.00",
      "discount": "0.00",
      "discount_formatted": "€0.00",
      "tax": "1900.00",
      "tax_formatted": "€1,900.00",
      "total": "11900.00",
      "total_formatted": "€11,900.00",
      "credited": "0.00",
      "credited_formatted": "€0.00",
      "amount_paid": "3570.00",
      "amount_paid_formatted": "€3,570.00",
      "balance": "8330.00",
      "balance_formatted": "€8,330.00",
      "taxes": [
        {
          "rate": "19",
          "base": "10000.00",
          "amount": "1900.00",
          "amount_formatted": "€1,900.00"
        }
      ]
    },
    "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": "a771fd09-fd0c-4770-b321-04a0c9d0f2e1",
      "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/a771fd09-fd0c-4770-b321-04a0c9d0f2e1?t=eyJmIjoiYTc3MWZkMDktZmQwYy00NzcwLWIzMjEtMDRhMGM5ZDBmMmUxIiwiZXhwIjoxNzkyNDYyMDAxfQ:1xIclt:wHbNTYfSeJwiecOWoutZMq4siLEJpMIfzpZLwzigbDU",
      "link_expires_in_hours": 24
    },
    "payments": [
      {
        "payment_id": 4101,
        "amount": "3570.00",
        "amount_formatted": "€3,570.00",
        "date": "2026-10-14",
        "method": "credit",
        "reference": "CR-0001",
        "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": null,
    "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": "3570.00",
    "amount_formatted": "€3,570.00",
    "date": "2026-10-14",
    "method": "credit",
    "reference": "CR-0001",
    "note": "",
    "recorded_at": "2026-10-14T08:00:00+00:00"
  },
  "entry": 3
}

Use it when

A customer with a deposit or an overpayment gets an invoice, asks for the money back, or a deposit was recorded by mistake (void).

What it does

Put a customer's credit (a prepayment or an overpayment) on one of their sent invoices, like Xero's allocate credit: invoice_id, and amount (default all it can: what is left on the credit or the invoice, the smaller); the invoice records it as a payment with method credit, and its share of the credit's VAT comes back off. Or refund: true pays what is left (or amount) back to the customer, with date and method; or void: true takes back a prepayment recorded by mistake while none of it is used. Same customer and currency only.

What comes back

credit: what is left and how it was used; with an invoice, the invoice, the payment and the entry; with refund, the entry. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
creditRequiredstringThe credit's number, like "CR-0001" (invoices_list_credits). 1 to 20 characters.
invoice_idstringThe invoice_id invoices_create returned (quotes and credit notes have one too). Exactly 36 characters.
amountnumber or stringUp to 24 characters.
refundbooleanDefault: false.
voidbooleanDefault: false.
datestringYYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
methodstringOne of: bank_transfer,card,cash,check,online,other. Default: bank_transfer.
referencestringUp to 120 characters.

The call

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

Terminal
curl -X POST https://api.conecto.chat/v1/tools/invoices_use_credit \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credit":"CR-0001","invoice_id":"7b1f6d2e-3c4a-4e8f-9a1b-2c3d4e5f6a7b"}'

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.
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.
invalid_input400Not exactly one of invoice_id, refund and void; or an amount or date that is not valid.Fix what the message names.
not_found404No credit has that number.List them with invoices_list_credits.
more_than_left409The credit has less left than the amount, or nothing.Use or pay back at most what is left.
more_than_balance409The invoice owes less than the amount.Leave amount out to use what fits.
other_customer409The invoice is another customer's.Use it on this customer's invoices.
currency_mismatch409The invoice is in another currency.Use it on an invoice in its currency.
not_sent409The invoice is a draft.Send it first.
void409The invoice is void.Use it on another invoice.
already_paid409The invoice is paid in full.Use it on another invoice, or pay it back.
in_use409Void: some of the deposit is used or paid back already.Pay back what is left instead.

More Invoices tools

All 24 tools

Give this to your agent.

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