The write contract¶

These are the rules that make Konto accept a create/update. The server validates them and rejects payloads that break them — getting these right is 90 % of a successful integration.

Sending write payloads¶

Create/update endpoints read the object from a data field. Send it as a JSON-encoded string (universal, and what the official MCP/SDK uses):

{ "data": "{\"name\":\"Acme ehf\",\"kennitala\":\"1234567890\",\"email\":\"acme@example.is\"}" }

Customer endpoints additionally accept the object nested ({"data":{…}}) or the fields flat at the top level. The API reference documents the decoded object for each endpoint.

Codes you'll need¶

VAT rate — `tax`¶

Code	Rate	Use for
`S`	24 %	standard-rated goods & services
`AA`	11 %	reduced rate (books, food, accommodation…)
`Z`	0 %	zero-rated / exempt

Warning

konto_create_item / item creation defaults tax to Z (0 %) if you omit it. Set S or AA explicitly for taxable items.

Unit of measure — `uom`¶

Code	Unit	Code	Unit
`C62`	pieces	`KWH`	kWh
`HUR`	hours	`MTK`	m²
`DAY`	days	`MTQ`	m³
`MIN`	minutes	`TNE`	tonnes
`KGS`	kg	`LTR`	litres
`MTR`	metres	`KTM`	km

Payment method — `how_paid` (costs)¶

1 = Account/bank transfer · 2 = Debit card · 3 = Credit card · 4 = Owner cash.

Invoice delivery — `output_select` (customers)¶

2 = e-invoice / XML (requires trading_partner_id) · 3 = email (default) · 4 = PDF (email optional).

Cost code — `type` (costs)¶

A cost needs a numeric cost code. There is no public name→code lookup (only Items → 2353 is a documented alias). Accepted codes:

3028 2173 3033 3085 3090 2093 2243 2193 2423 2443 2353 2383 2403
2263 3163 2333 3140 2283 2533 2633 3653 5028 2153 3080 9535

If you're unsure which to use, either ask Konto for the mapping, or upload the receipt to POST /agent/costs and let Cost AI fill the code from the document.

Invoices¶

amount must equal Σ(line items) + VAT, rounded to 2 decimals. The server rejects a mismatch — compute it from the exact items you send.
Date chain: issue_date ≤ due_date ≤ settlement_date.
- issue_date (útgáfudagur) — defaults to today if omitted.
- due_date (gjalddagi) — defaults to issue_date.
- settlement_date (eindagi) — the last date before collection. Required; must be ≥ due_date.
Line items are either an existing catalogue item (guid + qty) or a new inline item (add_new: 1 + description + unit_price + tax + uom + qty).
New inline lines need an item_number — Konto's validation requires it even though the save step would auto-number. Supply one (any unique SKU string).
Credit note: type: credit + ref_invoice_guid — the original is marked credited and its customer is inherited.

{
  "amount": 24800,
  "currency": "ISK",
  "customer": { "guid": "c1a2…" },
  "issue_date": "2026-01-15",
  "due_date": "2026-01-29",
  "settlement_date": "2026-02-12",
  "items": [
    { "add_new": 1, "description": "Consulting", "qty": 10,
      "unit_price": 2000, "uom": "HUR", "tax": "S", "item_number": "10000001" }
  ]
}

10 × 2000 = 20 000 + 24 % VAT = 24 800 ✓

Customers¶

kennitala — 10 digits, no dash (e.g. 1234567890); validated with a mod-11 checksum.
email — required for the default email delivery; optional only when output_select = 4 (PDF).
trading_partner_id (e-invoice recipient) — the recipient's bare kennitala. Do not prefix the Peppol scheme 0196: — the API assumes it.
Create does not dedupe by kennitala — each POST makes a new profile. To change an existing one, fetch it then PUT.

Costs¶

Keep amount positive even for a credit note — set credit_note: 1 to mark it; the server produces the credit document.
vat_11 / vat_24 are amounts in ISK, not rates.
supplier_id is the supplier's kennitala.

Accounting status (invoices & costs)¶

Updates change only the bookkeeping status, not the contents: Created → Posted (terminal, locked) / Skipped / Error. To edit a Created cost's data, reopen it (move to New) first, then re-approve — that regenerates its bookkeeping XML.