Credit an invoice

invoices_create_credit_note · Changes data · Markdown

Corrects a sent invoice with a numbered credit note: all of it, some of its lines or an amount, emailed like an invoice.

$0.10 a call

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

Hotel Elbblick sent two of the forty chairs back and we transferred the money. Credit them on their invoice.

Your agent callsinvoices_create_credit_note$0.10 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",
  "lines": [
    {
      "line": 1,
      "quantity": 2
    }
  ],
  "reason": "Returned: 2 bistro chairs, beech",
  "refunded": true,
  "method": "bank_transfer",
  "reference": "Refund INV-0042"
}

What comes back

{
  "credit_note": {
    "invoice_id": "23d0eed6-75cd-4a18-87b5-66b2f6402265",
    "kind": "credit_note",
    "number": "CN-0001",
    "status": "sent",
    "currency": "EUR",
    "issue_date": "2026-10-14",
    "credit_for": {
      "invoice_id": "2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f",
      "number": "INV-0042",
      "issue_date": "2026-10-14"
    },
    "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": "685.44",
    "total_formatted": "€685.44",
    "amount_paid": "0.00",
    "balance": "0.00",
    "balance_formatted": "€0.00",
    "public_url": "https://cncto.co/i/qKGfOLD2wDXX42BiyCVVv-pql77AbuBR",
    "created_at": "2026-10-14T08:00:00+00:00",
    "sent_at": "2026-10-14T08:00:00+00:00",
    "items": [
      {
        "description": "Bistro chair, beech\nStackable, for terraces",
        "quantity": "2",
        "unit_price": "320",
        "tax_rate": "19",
        "discount_percent": "10",
        "amount": "640.00",
        "discount": "64.00",
        "tax": "109.44",
        "total": "685.44"
      }
    ],
    "totals": {
      "subtotal": "640.00",
      "subtotal_formatted": "€640.00",
      "discount": "64.00",
      "discount_formatted": "€64.00",
      "tax": "109.44",
      "tax_formatted": "€109.44",
      "total": "685.44",
      "total_formatted": "€685.44",
      "credited": "0.00",
      "credited_formatted": "€0.00",
      "amount_paid": "0.00",
      "amount_paid_formatted": "€0.00",
      "balance": "0.00",
      "balance_formatted": "€0.00",
      "taxes": [
        {
          "rate": "19",
          "base": "576.00",
          "amount": "109.44",
          "amount_formatted": "€109.44"
        }
      ]
    },
    "supply": null,
    "tax_exemption": null,
    "tax_note": null,
    "vat_exchange_rate": null,
    "national_vat": null,
    "e_invoice": null,
    "notes": "Returned: 2 bistro chairs, beech",
    "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": "e5f19bad-ab66-45c6-969a-c20f0e84bcef",
      "name": "Credit note CN-0001.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/e5f19bad-ab66-45c6-969a-c20f0e84bcef?t=eyJmIjoiZTVmMTliYWQtYWI2Ni00NWM2LTk2OWEtYzIwZjBlODRiY2VmIiwiZXhwIjoxNzkyMTYwODk3fQ:1xHMRN:oeU669yLUcbi-FfrDzo0RV8SUr5Bt3l3LWfOBetK82U",
      "link_expires_in_hours": 24
    },
    "payments": [],
    "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": "for invoice INV-0042",
        "by": "key 4101 (Pip)"
      },
      {
        "at": "2026-10-14T08:00:00+00:00",
        "event": "sent",
        "detail": "CN-0001",
        "by": "key 4101 (Pip)"
      }
    ]
  },
  "invoice": {
    "invoice_id": "2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f",
    "kind": "invoice",
    "number": "INV-0042",
    "status": "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": "13201.86",
    "balance": "0.00",
    "balance_formatted": "€0.00",
    "public_url": "https://cncto.co/i/t9QqQyTB5da5rk7G_WrtZPdGLMyXi93D",
    "created_at": "2026-10-14T08:00:00+00:00",
    "sent_at": "2026-10-14T08:00:00+00:00",
    "credited": "685.44"
  },
  "refund": {
    "payment_id": 4102,
    "amount": "-685.44",
    "amount_formatted": "-€685.44",
    "date": "2026-10-14",
    "method": "bank_transfer",
    "reference": "Refund INV-0042",
    "note": "Credit note CN-0001",
    "recorded_at": "2026-10-14T08:00:00+00:00"
  },
  "emailed_to": "lukas.meyer@hotel-elbblick.example"
}

Use it when

Goods came back, a sent invoice was wrong, or the customer gets money off. In much of the EU a sent invoice is corrected this way, not voided.

For a draft that was never sent, use invoices_update.

What it does

Issue a credit note against a sent invoice: all of it, some of its lines, or an amount. It takes the next credit note number (gapless, CN-0001...), gets a PDF and a page like an invoice, and is emailed to the customer unless email is false. It lowers what the customer still owes; refunded: true says the money went back to them instead, and the invoice records the refund. In much of the EU a sent invoice is corrected this way, not voided. When the account keeps books, the sale and its tax are reversed there.

What comes back

credit_note: the credit note with its number, the invoice it corrects (number and date, as its PDF and page name it), lines, totals, page and PDF; invoice: the invoice with what is credited and what is still owed; refund: the refund recorded on the invoice when the money went back; emailed_to. Every reply also carries cost_usd and balance_usd.

Inputs

Name	Type	What it is
`invoice_id`Required	string	The invoice_id invoices_create returned (quotes and credit notes have one too). Exactly 36 characters.
`lines`	array of objects	Lines of the invoice to credit, at its prices. Leave out lines and amount to credit the whole invoice (or what is left of it). 1 to 200 items.
`lines[].line`Required	integer	The invoice's line number, from 1, in the order invoices_get lists its items. At least 1.
`lines[].quantity`	number or string	How many to credit. Default: all of the line not credited yet. Up to 24 characters.
`amount`	number or string	A sum to credit, tax included, e.g. "50.00" off for a late delivery. Its tax follows the invoice's rates (or those of `lines`, when given too). Up to 24 characters.
`reason`	string	Printed on the credit note, e.g. "Returned: 1 bike rack". Up to 500 characters.
`refunded`	boolean	true: the money went back to the customer (say how with method and reference). false: the credit lowers what they still owe. Default: false.
`method`	string	With refunded: how the money went back. One of: bank_transfer,card,cash,check,online,other. Default: other.
`reference`	string	With refunded: e.g. the bank transfer or refund id. Up to 120 characters.
`email`	boolean	false: issue it without emailing anyone. Default: true.
`to`	string	Email it to this address instead of the customer's. Up to 254 characters.
`message`	string	A short note in the email. Up to 2,000 characters.
`link_hours`	integer	How long the PDF download link works, in hours (up to 168). 1 to 168. Default: 24.

The call

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

Terminal

curl -X POST https://api.conecto.chat/v1/tools/invoices_create_credit_note \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f","lines":[{"line":1,"quantity":2}],"reason":"Returned: 2 bistro chairs, beech","refunded":true,"method":"bank_transfer","reference":"Refund INV-0042"}'

When it refuses

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

Code	When	What to do
`not_found`404	No quote or invoice of the business has that invoice_id.	Find it with invoices_list and use its invoice_id.
`not_an_invoice`400	The id is a quote or a credit note.	Credit notes go against invoices.
`not_sent`409	The invoice is still a draft.	Change the draft with invoices_update instead.
`void`409	The invoice is void.	A void invoice owes nothing and takes no credit note.
`already_credited`409	A line named is credited in full already.	Credit other lines, or an amount.
`more_than_invoiced`409	The credit is more than what is left of the invoice, or of a line.	Credit at most what the message says is left.
`more_than_balance`409	The credit is more than what is still owed, and refunded is not true.	If the money went back to the customer, pass refunded: true.
`more_than_paid`409	refunded is true, but less than the credit was ever paid.	Credit at most what was paid, or leave refunded out to lower what is owed.
`nothing_to_credit`409	Everything on the invoice is credited already.	To charge the customer again, send a new invoice.
`invoice_incomplete`409	The invoice lacks what the law of the business's country needs on it: the business's address or VAT ID, the customer's VAT ID or address for a reverse charge, why a line has no tax.	Add what the message names (invoices_update, invoices_set_profile) and send again; nothing was numbered.
`national_system_required`409	The business is in a country whose domestic invoices must go through a national system (Italy, Poland, Belgium, Croatia, Romania, Hungary, Greece, Portugal; Spain from 2027, France from September 2027).	Send it through that system; invoices to customers abroad still work.
`vat_id_invalid`409	VIES says the customer's VAT ID is not valid, so the reverse-charge or intra-Community invoice can't go out.	Check the number with the customer and fix customer.tax_id with invoices_update.
`no_rate`409	The invoice is in another currency than the national one and its VAT must be shown in both, but there is no rate for the day.	Pass vat_exchange_rate with invoices_update (UK businesses always give it).
`invalid_input`400	A line, amount, date, currency, country, email or link is not valid, or the total comes out negative or too large.	Fix what the message names: amounts like 19.99, dates like 2026-11-20, currencies like EUR.
`no_email`409	The document has no customer email to send to.	Pass to, or set customer.email on the draft with invoices_update.
`payment_required_for_outbound`402	The balance is still free credit, which cannot email people outside the business.	Top up once (POST /v1/topups), or send with email: false and hand the link over yourself.
`suppressed`422	The address bounced, complained or unsubscribed before.	Send to another address with to.
`too_many_emails`429	This document was emailed as often as it may in 24 hours.	Try again tomorrow.
`daily_email_limit`429	The business emailed as many quotes and invoices in 24 hours as it may.	Try again tomorrow, or ask Conecto for more.
`email_failed`502	The email could not be sent; nothing was charged.	Call again in a moment.
`before_start`409	The date is before the books start.	Use a later date, or set an earlier start with books_setup.
`period_locked`409	The books are locked for that date.	Use a later date, or unlock the period with books_lock.
`no_role`409	The 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

Credit an invoice

An example

Use it when

What it does

What comes back

Inputs

The call

When it refuses

More Invoices tools

Give this to your agent.