/merit-sales-invoices

name: merit-sales-invoices
version: 1.0.0
description: >
  How to create, find, credit, and send sales invoices correctly in Merit Aktiva
  (müügiarve) via the elnora-merit CLI. Covers customer resolution, VAT tax-code
  selection, self-managed invoice numbering, prepayment invoices, credit notes, and
  delivery by e-mail / e-invoice.
  Use when: creating a sales invoice, billing a customer, issuing a credit note,
  recording a prepayment invoice, sending an invoice as an e-invoice or PDF, or
  finding/looking up an existing sales invoice.
  TRIGGERS: "create sales invoice", "create invoice", "müügiarve", "bill the customer",
  "issue invoice", "credit note", "kreeditarve", "prepayment invoice", "ettemaksuarve",
  "send invoice", "e-invoice", "e-arve", "invoice PDF", "find invoice", "unpaid invoices".

Merit Sales Invoices (müügiarve)

How to issue sales invoices correctly with `elnora-merit sales-invoices`. Every endpoint is **POST with a JSON body**. Writes hit the live books and feed the VAT return — confirm the payload before posting.

> For real codes, load the **company profile** (`elnora-merit profile sync` → `company-profile.json` > in `MERIT_REFERENCES_DIR`): revenue accounts, VAT guids, customers. Conventions the codes > don't capture (the next invoice number, customer specifics) come from your prose books > reference if you keep one. Load what applies before building a payload.

The five rules that prevent most mistakes

1. **You manage the invoice number.** Merit issues none and there is no get-next-number endpoint. `InvoiceNo` is required and must be unique; read your last number (`sales-invoices find --inv-no …` or your books reference) and increment. Never guess silently — confirm the number with the user. 2. **VAT is chosen by `TaxId`, not a percentage.** Get the guid from `elnora-merit taxes list` (each row: `Id`, `Code` like `24%`, `TaxPct`). Put that `TaxId` on every `InvoiceRow`, and repeat it in the top-level `TaxAmount` array (grouped + summed per `TaxId`). `TotalAmount` is the net **without** VAT. 3. **The API cannot update an invoice — but the Merit UI can.** There is no update endpoint, so via the API you `delete <id>` (requires the user's go-ahead) and create it again. Do **not** conclude the change is impossible: the UI edits invoices in place, keeping the number, dates and payment. Before proposing delete-and-recreate for a field-level fix (wrong customer, typo in a line), say so and let the user decide — the UI route is almost always the better one. See [reference/paid-invoices.md](reference/paid-invoices.md). 4. **Resolve the customer before billing.** Reuse an existing customer by `Id`; only create a new one when none matches. `customers list` MUST be filtered. 5. **A paid invoice is locked.** Merit refuses both the delete (`400`, "Tasutud arvet ei saa kustutada. Enne kustutage makse.") and, in the UI, any change of customer, currency or currency rate ("Arve on juba tasutud. Ei saa muuta klienti, valuutat ja valuutakurssi ega vähendada summat."). The payment must come off first. Full procedure: [reference/paid-invoices.md](reference/paid-invoices.md).

Resolve / create the customer

# find (ALWAYS filter — unfiltered customers list returns a server error)
elnora-merit customers list --name "Acme"        # broad match
elnora-merit customers list --reg-no 12345678    # exact
elnora-merit customers list --vat-reg-no EE123456789

If none matches, create one. Required: `Name` (unique), `CountryCode` (2-letter), `NotTDCustomer` (lowercase `"true"`/`"false"` — `true` for private persons and foreign companies, `false` for a domestic tax-registered company):

elnora-merit customers create --data '{"Name":"Acme OÜ","CountryCode":"EE",
  "NotTDCustomer":"false","RegNo":"12345678","VatRegNo":"EE123456789",
  "Email":"billing@acme.ee","PaymentDeadLine":14,"SalesInvLang":"EN"}'

For an EU customer, set the real `CountryCode` and `VatRegNo` (Merit validates EU VAT via VIES). The invoice language is a customer property (`SalesInvLang`), not a setting.

Two fields bite later, so get them right now:

• **`Email`** is where `send-email` silently sends every future invoice. An address

someone typed in a message is not a verified address. If a send to it bounces, fix the customer record — don't just work around it for one invoice, or the next invoice bounces too and nobody notices. Never guess a variant of a bounced address: an invoice is a financial document and the guess may belong to a stranger.

• **`PaymentDeadLine`** sets the due date on every invoice for this customer, and it

re-derives the due date if the invoice is later re-saved against them. See [reference/paid-invoices.md](reference/paid-invoices.md).

Create the invoice

Read the full field schema with `elnora-merit sales-invoices create --help`, or [reference/fields.md](reference/fields.md). Build the body and post:

elnora-merit sales-invoices create --file invoice.json

Minimum viable body (existing customer, one line, standard VAT):

{
  "Customer": { "Id": "<customer-guid>" },
  "InvoiceNo": "2026-014",
  "DocDate": "20260606000000",
  "DueDate": "20260620000000",
  "InvoiceRow": [
    { "Item": { "Code": "CONSULT", "Description": "Consulting", "Type": 2 },
      "Quantity": 1, "Price": 1000.00, "TaxId": "<taxid-from-gettaxes>" }
  ],
  "TaxAmount": [ { "TaxId": "<same-taxid>", "Amount": 240.00 } ],
  "TotalAmount": 1000.00
}

• Body dates are `YYYYMMDDHHMMSS`; query dates (`list`) are `YYYYMMDD`.
• `Item.Type`: `1` stock, `2` service, `3` item. `Price` is net per unit.
• Use **`create-v2`** instead when you tag dimensions (cost centre / project / department

as a `Dimensions` array) or need a non-local `CurrencyRate`.

• The API returns `{ CustomerId, InvoiceId, InvoiceNo, RefNo, NewCustomer }`. `RefNo`

(viitenumber) is auto-derived from the number if you omit it.

Prepayment i