Method

payment.process

Record an owner's payment and apply it to chosen documents, or to the oldest open ones.

Records a payment by a customer, or to a vendor or employee, and applies it to the documents you choose (applyTo, in that order), or with autoPay to all the owner's open documents, oldest first. amount is in the A/R or A/P account's commodity and positive when a customer pays or you pay a vendor or employee; negative is a refund.

What is left over becomes a pre-payment, a lot with no document, and is returned as paymentLot; it is applied later by a new payment of amount 0 naming it in applyTo. With neither applyTo nor autoPay the whole payment is a pre-payment. An amount of 0 records no transaction and only links the lots named.

To pay in a commodity other than the account's, give exchangeRate.

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":"payment.process","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable","transferAccount":"Assets:Bank","amount":"300.00","date":"2024-03-25","applyTo":["aa210b7131de44c48b8513cd27c00e95"]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction": "…",
    "paymentLot": null
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"payment.openItems","params":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "items": [
      {
        "invoice": "aa210b7131de44c48b8513cd27c00e95",
        "balance": {
          "num": "57300",
          "denom": "100"
        },
        "…": "…"
      }
    ]
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
payment.process {"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable","transferAccount":"Assets:Bank","amount":"300.00","date":"2024-03-25","applyTo":["aa210b7131de44c48b8513cd27c00e95"]}
payment.openItems {"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}
EOF

It prints:

[
  {
    "transaction": "…",
    "paymentLot": null
  },
  {
    "items": [
      {
        "invoice": "aa210b7131de44c48b8513cd27c00e95",
        "balance": {
          "num": "57300",
          "denom": "100"
        },
        "…": "…"
      }
    ]
  }
]

MCP tool call

Tool call:

{"name":"payment.process","arguments":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable","transferAccount":"Assets:Bank","amount":"300.00","date":"2024-03-25","applyTo":["aa210b7131de44c48b8513cd27c00e95"]}}

Result:

{
  "structuredContent": {
    "transaction": "…",
    "paymentLot": null
  }
}

Tool call:

{"name":"payment.openItems","arguments":{"owner":{"type":"customer","id":"5b22073fa4e34411b07c14a77147ce6b"},"account":"Assets:Receivable"}}

Result:

{
  "structuredContent": {
    "items": [
      {
        "invoice": "aa210b7131de44c48b8513cd27c00e95",
        "balance": {
          "num": "57300",
          "denom": "100"
        },
        "…": "…"
      }
    ]
  }
}

Paying a vendor without saying what for leaves a pre-payment:

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

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"payment.process","params":{"owner":{"type":"vendor","id":"9697710198334d558a9bfde219bb1e41"},"account":"Liabilities:Payable","transferAccount":"Assets:Bank","amount":"10.00","date":"2024-03-25"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction": "…",
    "paymentLot": "…"
  }
}

Command line

red-ale exec --book book.gnucash payment.process '{"owner":{"type":"vendor","id":"9697710198334d558a9bfde219bb1e41"},"account":"Liabilities:Payable","transferAccount":"Assets:Bank","amount":"10.00","date":"2024-03-25"}'

It prints:

{
  "transaction": "…",
  "paymentLot": "…"
}

MCP tool call

Tool call:

{"name":"payment.process","arguments":{"owner":{"type":"vendor","id":"9697710198334d558a9bfde219bb1e41"},"account":"Liabilities:Payable","transferAccount":"Assets:Bank","amount":"10.00","date":"2024-03-25"}}

Result:

{
  "structuredContent": {
    "transaction": "…",
    "paymentLot": "…"
  }
}

Effect: write, on the Book.

Params

Params of payment.process.

  • owner (OwnerParam, required): Who pays or is paid.
  • account (AccountRef, required): The A/Receivable or A/Payable account the documents are posted to.
  • transferAccount (AccountRef or null): Where the money goes (customer payments) or comes from (vendor and employee payments). Needed unless the amount is zero.
  • amount (Amount, required): The payment, in the A/R or A/P account's commodity: positive when a customer pays or when a vendor or employee is paid; negative for a refund. Zero links the chosen documents with each other only.
  • exchangeRate (Amount or null): Units of the transfer account's commodity per unit of the A/R or A/P account's commodity, when they differ.
  • date (Date, required): The payment date.
  • memo (string or null): Memo of both splits.
  • num (string or null): Transaction number (a check number).
  • applyTo (array of Guid): Documents (invoice GUIDs) and pre-payment lots (lot GUIDs) to apply the payment to, in order.
  • autoPay (boolean): With no applyTo: apply to all the owner's open documents and pre-payments (GnuCash's preference, default false).

Result

Result of a payment.

  • transaction (Guid or null): The payment transaction (none when the amount is zero).
  • paymentLot (Guid or null): The lot holding what was not applied: a pre-payment.