Method

invoice.update

Change an unposted document, or (de)activate any document.

Changes an unposted document: its owner, number, dates, billing term, notes, document link and the like. A new owner must give the same kind of document (another customer, or one of a customer's jobs, for an invoice), and the currency follows the owner. Whether it is a credit note cannot change.

A posted document can only be activated or deactivated, or have its document link changed; any other change is refused with conflict. Unpost it first with invoice.unpost.

Examples

Example: with a copy of the synthetic/business-editable example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"invoice.update","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","notes":"Phase 1"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "71803cac5d8e4dceabfd0d56ec5e7521",
    "notes": "Phase 1",
    "posted": false,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"invoice.update","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","notes":"Phase 1"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2003,
    "message": "document 000001 is posted; only its active flag can change",
    "data": {
      "help": "error/conflict"
    }
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"invoice.update","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","active":false}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "guid": "aa210b7131de44c48b8513cd27c00e95",
    "active": false,
    "posted": true,
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
invoice.update {"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","notes":"Phase 1"}
invoice.update {"invoice":"aa210b7131de44c48b8513cd27c00e95","notes":"Phase 1"}
invoice.update {"invoice":"aa210b7131de44c48b8513cd27c00e95","active":false}
EOF

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2003,
    "message": "document 000001 is posted; only its active flag can change",
    "data": {
      "help": "error/conflict"
    }
  }
}

MCP tool call

Tool call:

{"name":"invoice.update","arguments":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","notes":"Phase 1"}}

Result:

{
  "structuredContent": {
    "guid": "71803cac5d8e4dceabfd0d56ec5e7521",
    "notes": "Phase 1",
    "posted": false,
    "…": "…"
  }
}

Tool call:

{"name":"invoice.update","arguments":{"invoice":"aa210b7131de44c48b8513cd27c00e95","notes":"Phase 1"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "document 000001 is posted; only its active flag can change",
      "data": {
        "help": "error/conflict"
      }
    }
  }
}

Tool call:

{"name":"invoice.update","arguments":{"invoice":"aa210b7131de44c48b8513cd27c00e95","active":false}}

Result:

{
  "structuredContent": {
    "guid": "aa210b7131de44c48b8513cd27c00e95",
    "active": false,
    "posted": true,
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of invoice.update: the fields to change. Posted documents accept only active.

  • invoice (Guid, required): The document.
  • owner (Guid or null): A customer (invoice), vendor (bill), employee (expense voucher) or job (its owner's type). On update it can change only to an owner of the same type; the currency follows the owner.
  • id (string or null): Document number. On create, absent or empty takes the next number from the counter of the type (gncInvoice, gncBill or gncExpVoucher).
  • dateOpened (Date or null): Date opened; stored as noon local time. Defaults to today.
  • terms (BillTermRef or null): Billing term, by GUID or name; null for none. On create, absent takes the owner's term.
  • billingId (string or null): The customer's reference (purchase order number) or the vendor's invoice number.
  • notes (string or null): Notes.
  • docLink (string or null): A document link: a URL, a file:// URI, or a path relative to the path head. Empty removes it. Posted documents accept it too.
  • billTo (Guid or null): Bills and vouchers: the customer or job the costs are for; null for none.
  • chargeAmount (Amount or null): Vouchers: an extra amount to charge to the employee's credit card when posted.
  • active (boolean or null): Active; false deactivates.
  • creditNote (boolean or null): A credit note (default false). Fixed once the document exists: an update may only repeat it.

Result

A document with its lines, in GnuCash's order (date, date entered, description, action, GUID).

  • guid (Guid, required): A GUID: 32 hexadecimal digits.
  • id (string, required)
  • type (DocumentKindWire or null): From the owner (through a job to its owner) and the credit-note flag.
  • owner (OwnerInfo, required): An owner: a customer, vendor, employee or job.
  • currency (CommodityId or null)
  • dateOpened (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix.
  • posted (boolean, required)
  • datePosted (Timestamp or null)
  • terms (Guid or null)
  • billingId (string, required)
  • notes (string, required)
  • docLink (string or null): The document link (assoc_uri slot), as stored.
  • active (boolean, required)
  • billTo (OwnerInfo or null)
  • chargeAmount (Amount, required): An exact amount. Read from a decimal string ("12.34"), a rational string ("1234/100") or {num, denom} with string members; written as {num, denom}. Never a JSON number.
  • postedAccount (Guid or null)
  • postedTransaction (Guid or null)
  • postedLot (Guid or null)
  • entryCount (integer (uint), required)
  • entries (array of EntryInfo, required): Its lines.