Method

invoice.pay

Record a payment of one posted document.

Records a payment of one posted document: a transaction between the A/R or A/P account and transferAccount, applied to that document only. amount is positive when a customer pays or when you pay a vendor or employee; a negative amount is a refund. A payment of less than the balance leaves the rest open; one of more leaves a pre-payment.

To pay several documents at once, or an owner's oldest first, use payment.process.

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.pay","params":{"invoice":"95e2e7416db94eb3a7de7433f3e7875f","transferAccount":"Assets:Bank","amount":"20.00","date":"2024-03-25","memo":"Part payment"}}

Response:

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

Request:

{"jsonrpc":"2.0","id":2,"method":"invoice.pay","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","transferAccount":"Assets:Bank","amount":"1.00","date":"2024-03-25"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2001,
    "message": "document 000002 is not posted",
    "data": {
      "help": "error/invalid"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
invoice.pay {"invoice":"95e2e7416db94eb3a7de7433f3e7875f","transferAccount":"Assets:Bank","amount":"20.00","date":"2024-03-25","memo":"Part payment"}
invoice.pay {"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","transferAccount":"Assets:Bank","amount":"1.00","date":"2024-03-25"}
EOF

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

{
  "error": {
    "code": 2001,
    "message": "document 000002 is not posted",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"invoice.pay","arguments":{"invoice":"95e2e7416db94eb3a7de7433f3e7875f","transferAccount":"Assets:Bank","amount":"20.00","date":"2024-03-25","memo":"Part payment"}}

Result:

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

Tool call:

{"name":"invoice.pay","arguments":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","transferAccount":"Assets:Bank","amount":"1.00","date":"2024-03-25"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "document 000002 is not posted",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of invoice.pay.

  • invoice (Guid, required): The posted document.
  • transferAccount (AccountRef, required): Where the money goes or comes from.
  • amount (Amount, required): The payment, signed as in payment.process.
  • 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.

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.