conecto. Get started
Invoices

Create a quote or invoice

invoices_create · Changes data · Markdown

Creates a draft quote or invoice: the customer, the lines, the currency and the dates.

$0.01 a call

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

An example

Quote Hotel Elbblick for 40 beech bistro chairs for the terrace at 320 euros each before VAT, 10% off for the volume, plus 150 for delivery.

Your agent callsinvoices_create$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
{
  "kind": "quote",
  "currency": "EUR",
  "customer": {
    "name": "Hotel Elbblick GmbH",
    "email": "lukas.meyer@hotel-elbblick.example",
    "address": "Elbchaussee 120\n22763 Hamburg"
  },
  "items": [
    {
      "description": "Bistro chair, beech\nStackable, for terraces",
      "quantity": 40,
      "unit_price": "320.00",
      "discount": 10
    },
    {
      "description": "Delivery and setup",
      "unit_price": "150.00"
    }
  ],
  "notes": "Thank you for your enquiry. The chairs can be delivered in week 49."
}
What comes back
{
  "invoice": {
    "invoice_id": "005ea1ee-dfd9-4cac-a569-45f94e97e248",
    "kind": "quote",
    "number": null,
    "status": "draft",
    "currency": "EUR",
    "issue_date": null,
    "valid_until": null,
    "expired": false,
    "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": "0.00",
    "balance": "13887.30",
    "balance_formatted": "€13,887.30",
    "public_url": null,
    "created_at": "2026-10-14T08:00:00+00:00",
    "sent_at": null,
    "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": "0.00",
      "amount_paid_formatted": "€0.00",
      "balance": "13887.30",
      "balance_formatted": "€13,887.30",
      "taxes": [
        {
          "rate": "19",
          "base": "11670.00",
          "amount": "2217.30",
          "amount_formatted": "€2,217.30"
        }
      ]
    },
    "supply": null,
    "tax_exemption": null,
    "tax_note": null,
    "vat_exchange_rate": null,
    "national_vat": null,
    "e_invoice": null,
    "notes": "Thank you for your enquiry. The chairs can be delivered in week 49.",
    "payment_link": null,
    "ready_to_send": true,
    "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": null,
    "payments": [],
    "invoice_ids": [],
    "response": {
      "name": null,
      "note": null
    },
    "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)"
      }
    ]
  }
}

Use it when

A customer should get a price (a quote) or a bill (an invoice). Nothing is numbered or sent yet.

What it does

Create a quote or an invoice as a draft: the customer (a CRM contact or company, or a name and email), line items, currency and dates. Nothing is numbered or sent yet; change drafts with invoices_update and send them with invoices_send. Amounts are the business's money in the document's currency, rounded half-up line by line.

What comes back

The draft with its invoice_id, kind and status, customer, lines with their amounts, totals and taxes, currency and dates. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
kindRequiredstringOne of: invoice,quote.
customerRequiredobjectWho the document is for. Link a CRM record with contact_id or company_id, or give name and email (an email that matches a CRM contact links it). What is given here is printed as it is.
customer.contact_idintegerA CRM contact; fills the name and email. At least 1.
customer.company_idintegerA CRM company; fills the name. At least 1.
customer.namestringWho is billed, as printed. Up to 200 characters.
customer.emailstringWhere the document is emailed. Up to 254 characters.
customer.addressstringPostal address, one line per row. Up to 1,000 characters.
customer.tax_idstringThe customer's VAT or tax number, for business customers. A reverse-charge or intra-EU invoice needs their EU VAT ID, e.g. "FR12345678901". Up to 60 characters.
customer.countrystringISO 3166-1 code of the customer's country, e.g. "FR". Checks intra_eu and export invoices; e-invoices need it. Up to 2 characters.
itemsRequiredarray of objects1 to 200 items.
items[].descriptionRequiredstringWhat was sold. Lines after the first print smaller, underneath. 1 to 2,000 characters.
items[].quantitynumber or stringDefault 1. Up to 6 decimals, e.g. 1.5 (hours). Up to 24 characters.
items[].unit_priceRequirednumber or stringThe price of one, before tax, e.g. "19.99". Negative for a credit line. Up to 24 characters.
items[].tax_ratenumber or stringTax percent, e.g. 19. Default: the profile's tax_rate. Up to 24 characters.
items[].discountnumber or stringDiscount percent on this line, e.g. 10. Up to 24 characters.
items[].accountstringWith books: the income account this line books to, e.g. "4100" for services. Default: the sales account. Up to 20 characters.
items[].trackingobjectWith books: tracking options, e.g. {"Department": "Service"}.
currencystringISO 4217, e.g. "USD", "EUR" or "JPY". Matches ^[A-Za-z]{3}$.
notesstringPrinted above the lines, e.g. "Thank you for your order" or a project reference. Up to 5,000 characters.
payment_linkstringAn https link to pay this document. Default: the profile's payment_link. Up to 500 characters.
tax_exemptionstringWhy lines with tax_rate 0 carry no tax, printed on the invoice as the law asks: exempt, zero_rated, reverse_charge (the customer accounts for the VAT), intra_eu (goods to a business in another EU country), export (goods leaving the EU), outside_scope, small_business (a business under its country's small-business VAT exemption, such as UStG §19 or art. 293 B CGI: no line may carry tax). Needed in the EU for any line without tax. Default: the profile's. One of: ,exempt,zero_rated,reverse_charge,intra_eu,export,outside_scope,small_business.
tax_exemption_notestringThe wording printed for the exemption instead of the standard one, e.g. "Steuerbefreit als Kleinunternehmer nach § 19 UStG". Up to 300 characters.
e_invoicestringInvoices and their credit notes as EN 16931 e-invoices (German B2B invoices must be from 2027): factur-x (Factur-X/ZUGFeRD, the XML inside the PDF/A-3) or xrechnung (XRechnung 3.0, its own XML beside the PDF), checked against the EN 16931 schema before sending. "" is the default: none, except that from 2027 an invoice from a German business to a German business above EUR 250 is a factur-x; "none" opts out (a business under the EUR 800,000 turnover allowance until 2028). Needs the customer's country. Default: the profile's. One of: ,factur-x,xrechnung,none.
vat_exchange_ratenumber or string or nullFor an invoice in another currency than the national one of the business's country: one unit of it in the national currency, for the VAT shown in both. Default in the EU: the European Central Bank's rate for the day of supply; UK businesses give it. Up to 24 characters.
supply_datestringInvoices: the day the goods or services were supplied, or the first day of a period. Default: the issue date, which the invoice then states. Matches ^\d{4}-\d{2}-\d{2}$.
supply_untilstringInvoices: the last day of the supply period, e.g. a month of service. Matches ^\d{4}-\d{2}-\d{2}$.
issue_datestringDefault: the day it is sent. Matches ^\d{4}-\d{2}-\d{2}$.
due_datestringInvoices. Default: issue date + the payment terms. Matches ^\d{4}-\d{2}-\d{2}$.
payment_terms_daysintegerInvoices: days to pay, instead of the profile's terms. 0 to 365.
valid_untilstringQuotes. Default: issue date + the profile's quote_valid_days. Matches ^\d{4}-\d{2}-\d{2}$.

The call

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

Terminal
curl -X POST https://api.conecto.chat/v1/tools/invoices_create \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"quote","currency":"EUR","customer":{"name":"Hotel Elbblick GmbH","email":"lukas.meyer@hotel-elbblick.example","address":"Elbchaussee 120\n22763 Hamburg"},"items":[{"description":"Bistro chair, beech\nStackable, for terraces","quantity":40,"unit_price":"320.00","discount":10},{"description":"Delivery and setup","unit_price":"150.00"}],"notes":"Thank you for your enquiry. The chairs can be delivered in week 49."}'

When it refuses

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

CodeWhenWhat to do
invalid_input400A 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.
not_found404The customer's contact_id or company_id is not in the business's CRM.Find the record with crm_search, or give a name and email instead.

More Invoices tools

All 24 tools

Give this to your agent.

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