--- name: "invoices_create_credit_note" area: "invoices" title: "Credit an invoice" price: "$0.10" method: "POST" url: "https://api.conecto.chat/v1/tools/invoices_create_credit_note" mcp_server: "https://api.conecto.chat/mcp/invoices" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/invoices/invoices_create_credit_note" --- # Credit an invoice (`invoices_create_credit_note`) Corrects a sent invoice with a numbered credit note: all of it, some of its lines or an amount, emailed like an invoice. 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. Price: $0.10 a call. A call that fails costs nothing. ## 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](https://conecto.chat/tools/invoices/invoices_update.md). ## Say this to your agent > Hotel Elbblick sent two of the forty chairs back and we transferred the money. Credit them on their invoice. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `invoice_id` | string | yes | The invoice_id invoices_create returned (quotes and credit notes have one too). Exactly 36 characters. | | | | `lines` | array of objects | no | 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` | integer | yes, in each item of `lines` | The invoice's line number, from 1, in the order invoices_get lists its items. At least 1. | | | | `lines[].quantity` | number or string | no | How many to credit. Default: all of the line not credited yet. Up to 24 characters. | | | | `amount` | number or string | no | 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 | no | Printed on the credit note, e.g. "Returned: 1 bike rack". Up to 500 characters. | | | | `refunded` | boolean | no | true: the money went back to the customer (say how with method and reference). false: the credit lowers what they still owe. | | `false` | | `method` | string | no | With refunded: how the money went back. | `"bank_transfer"`, `"card"`, `"cash"`, `"check"`, `"online"`, `"other"` | `"other"` | | `reference` | string | no | With refunded: e.g. the bank transfer or refund id. Up to 120 characters. | | | | `email` | boolean | no | false: issue it without emailing anyone. | | `true` | | `to` | string | no | Email it to this address instead of the customer's. Up to 254 characters. | | | | `message` | string | no | A short note in the email. Up to 2,000 characters. | | | | `link_hours` | integer | no | How long the PDF download link works, in hours (up to 168). 1 to 168. | | `24` | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `invoices_create_credit_note` on the MCP server `https://api.conecto.chat/mcp/invoices` with these arguments: ```json { "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" } ``` REST: ```bash curl 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"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "invoices_create_credit_note", "status": "succeeded", "replayed": false, "cost_usd": "$0.10", "balance_usd": "$19.75", "result": { "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" } } ``` `result`: 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. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `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. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [invoices_set_profile](https://conecto.chat/tools/invoices/invoices_set_profile.md): Sets the business details on quotes and invoices: name, country, address, tax ID, logo, terms, tax, numbering, how to pay and legal notes. $0.001 a call. - [invoices_get_profile](https://conecto.chat/tools/invoices/invoices_get_profile.md): The business details on quotes and invoices, the next numbers, and what is missing before documents can be sent. Free up to 1,000,000 reads a month. - [invoices_connect_stripe](https://conecto.chat/tools/invoices/invoices_connect_stripe.md): Connects the business's own Stripe account with a restricted key, so invoices can be paid online; the money goes straight to the business. $0.001 a call. - [invoices_create](https://conecto.chat/tools/invoices/invoices_create.md): Creates a draft quote or invoice: the customer, the lines, the currency and the dates. $0.01 a call. - [invoices_update](https://conecto.chat/tools/invoices/invoices_update.md): Changes a draft quote or invoice; customer and lines replace the old ones. $0.01 a call. - [invoices_send](https://conecto.chat/tools/invoices/invoices_send.md): Sends a draft: it gets the next number, its PDF is made, and the customer is emailed a link to view, pay or accept it. $0.10 a call. - [invoices_get](https://conecto.chat/tools/invoices/invoices_get.md): One quote or invoice in full, by invoice_id or number: lines, totals, taxes, payments, history, its page and a fresh PDF link. Free up to 1,000,000 reads a month. - [invoices_list](https://conecto.chat/tools/invoices/invoices_list.md): Quotes and invoices, newest first, by kind, status (also overdue, unpaid and expired), customer and issue date. Free up to 1,000,000 reads a month. - [invoices_convert_quote](https://conecto.chat/tools/invoices/invoices_convert_quote.md): Turns an accepted quote into a draft invoice with the same customer and lines. $0.01 a call. - [invoices_record_payment](https://conecto.chat/tools/invoices/invoices_record_payment.md): Records money received against a sent invoice, or a refund; the invoice becomes partially paid or paid. $0.01 a call. - [invoices_record_prepayment](https://conecto.chat/tools/invoices/invoices_record_prepayment.md): Records a customer's deposit before there is an invoice, like Xero's prepayments; it waits as their credit, with its VAT owed at once. $0.01 a call. - [invoices_use_credit](https://conecto.chat/tools/invoices/invoices_use_credit.md): Puts a customer's credit on their invoice, like Xero's allocate credit, or pays it back to them. $0.01 a call. - [invoices_list_credits](https://conecto.chat/tools/invoices/invoices_list_credits.md): Lists customers' credits, deposits and overpayments, with what is left on each. Free up to 1,000,000 reads a month. - [invoices_remind](https://conecto.chat/tools/invoices/invoices_remind.md): Emails the customer a reminder about a sent invoice with a balance, at most once a day. $0.02 a call. - [invoices_remind_overdue](https://conecto.chat/tools/invoices/invoices_remind_overdue.md): Emails a reminder about every invoice at least some days overdue, the longest overdue first. $0.02 per reminder sent. - [invoices_set_expected_date](https://conecto.chat/tools/invoices/invoices_set_expected_date.md): Notes 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. - [invoices_void](https://conecto.chat/tools/invoices/invoices_void.md): Voids a document: a sent one keeps its number but can no longer be paid or accepted; a draft is discarded. $0.01 a call. - [invoices_save_repeating](https://conecto.chat/tools/invoices/invoices_save_repeating.md): Makes 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. - [invoices_list_repeating](https://conecto.chat/tools/invoices/invoices_list_repeating.md): Lists the repeating invoices: who each is for, how often, the next dates, and what each made. Free up to 1,000,000 reads a month. - [invoices_delete_repeating](https://conecto.chat/tools/invoices/invoices_delete_repeating.md): Stops a repeating invoice for good; the invoices it made stay. Free. - [invoices_statement](https://conecto.chat/tools/invoices/invoices_statement.md): Makes a customer statement, outstanding or activity, as a PDF, and emails it when asked, like Xero's statements. $0.05 a call. - [invoices_summary](https://conecto.chat/tools/invoices/invoices_summary.md): What customers owe, per currency: outstanding, overdue and paid this month, and the quotes still open. Free up to 1,000,000 reads a month. - [invoices_report](https://conecto.chat/tools/invoices/invoices_report.md): Aged receivables on any day, or sales per customer for a period with the credit notes taken off. Free up to 1,000,000 reads a month.