Use or pay back a credit
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.
{
"credit": "CR-0001",
"invoice_id": "7b1f6d2e-3c4a-4e8f-9a1b-2c3d4e5f6a7b"
}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
| Name | Type | What it is |
|---|---|---|
creditRequired | string | The credit's number, like "CR-0001" (invoices_list_credits). 1 to 20 characters. |
invoice_id | string | The invoice_id invoices_create returned (quotes and credit notes have one too). Exactly 36 characters. |
amount | number or string | Up to 24 characters. |
refund | boolean | Default: false. |
void | boolean | Default: false. |
date | string | YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$. |
method | string | One of: bank_transfer,card,cash,check,online,other. Default: bank_transfer. |
reference | string | Up to 120 characters. |
The call
Over MCP, call invoices_use_credit on https://api.conecto.chat/mcp/invoices. Over REST:
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.
| Code | When | What to do |
|---|---|---|
not_found404 | No quote or invoice of the business has that invoice_id. | Find it with invoices_list and use its invoice_id. |
before_start409 | The date is before the books start. | Use a later date, or set an earlier start with books_setup. |
period_locked409 | The books are locked for that date. | Use a later date, or unlock the period with books_lock. |
no_role409 | The books have no account for a role the posting needs. | Give an account that role with books_save_accounts. |
invalid_input400 | Not exactly one of invoice_id, refund and void; or an amount or date that is not valid. | Fix what the message names. |
not_found404 | No credit has that number. | List them with invoices_list_credits. |
more_than_left409 | The credit has less left than the amount, or nothing. | Use or pay back at most what is left. |
more_than_balance409 | The invoice owes less than the amount. | Leave amount out to use what fits. |
other_customer409 | The invoice is another customer's. | Use it on this customer's invoices. |
currency_mismatch409 | The invoice is in another currency. | Use it on an invoice in its currency. |
not_sent409 | The invoice is a draft. | Send it first. |
void409 | The invoice is void. | Use it on another invoice. |
already_paid409 | The invoice is paid in full. | Use it on another invoice, or pay it back. |
in_use409 | Void: some of the deposit is used or paid back already. | Pay back what is left instead. |
More Invoices tools
All 24 tools- List customer credits
invoices_list_creditsLists customers' credits, deposits and overpayments, with what is left on each.Free* - Remind about an unpaid invoice
invoices_remindEmails the customer a reminder about a sent invoice with a balance, at most once a day.$0.02 a call - Remind everyone who is overdue
invoices_remind_overdueEmails a reminder about every invoice at least some days overdue, the longest overdue first.$0.02 per reminder sent - Set when a customer will pay
invoices_set_expected_dateNotes the day a customer says they will pay an invoice, so the cash flow forecast counts the money then, even when the invoice is overdue.Free - Credit an invoice
invoices_create_credit_noteCorrects a sent invoice with a numbered credit note: all of it, some of its lines or an amount, emailed like an invoice.$0.25 a call - Void a quote or invoice
invoices_voidVoids a document: a sent one keeps its number but can no longer be paid or accepted; a draft is discarded.$0.01 a call - Repeat an invoice
invoices_save_repeatingMakes an invoice again every so many weeks, months or years, drafted or sent on its day, with [Month] and [Year] filled in, like Xero's repeating invoices.$0.001 a call - List repeating invoices
invoices_list_repeatingLists the repeating invoices: who each is for, how often, the next dates, and what each made.Free*
Read next: AI bookkeeping: what it does, what it costs, and a two-month test, QuickBooks alternatives in 2026: eight options and what they cost, What is an MCP server?
Give this to your agent.
Set up Conecto from https://conecto.chat/SKILL.md