billTerm.create

Create a billing term (days or proximo).

Creates a billing term, the rule that says when a document is due. A days term is due dueDays after posting; a proximo term is due on day dueDays of the next month, and a document posted after day cutoff of the month is due a month later (a cutoff of 0 or less counts back from the end of the month).

discountDays and discount (a percentage) describe an early-payment discount. They are stored and shown only: red-ale does not take the discount off a payment. The discount days may not exceed the due days.

red-ale also refuses values GnuCash's dialog accepts but would compute an undefined due date from: negative days, a proximo due day outside 1-31, a cutoff outside -31 to 31, a discount outside 0-100.

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":"billTerm.create","params":{"name":"Net14","type":"days","dueDays":14}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "…",
    "name": "Net14",
    "type": "days",
    "dueDays": 14,
    "discountDays": 0,
    "refcount": 0,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"billTerm.create","params":{"name":"Bad","type":"days","dueDays":10,"discountDays":20}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2001,
    "message": "discount days cannot be more than due days",
    "data": {
      "help": "error/invalid"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
billTerm.create {"name":"Net14","type":"days","dueDays":14}
billTerm.create {"name":"Bad","type":"days","dueDays":10,"discountDays":20}
EOF

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

{
  "error": {
    "code": 2001,
    "message": "discount days cannot be more than due days",
    "data": {
      "help": "error/invalid"
    }
  }
}

MCP tool call

Tool call:

{"name":"billTerm.create","arguments":{"name":"Net14","type":"days","dueDays":14}}

Result:

{
  "structuredContent": {
    "guid": "…",
    "name": "Net14",
    "type": "days",
    "dueDays": 14,
    "discountDays": 0,
    "refcount": 0,
    "…": "…"
  }
}

Tool call:

{"name":"billTerm.create","arguments":{"name":"Bad","type":"days","dueDays":10,"discountDays":20}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2001,
      "name": "invalid",
      "message": "discount days cannot be more than due days",
      "data": {
        "help": "error/invalid"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of billTerm.create.

name (string, required): A name no other visible billing term has.
description (string): Description.
type (BillTermTypeWire, required): Days or proximo.
dueDays (integer (int64)): Days: days until due. Proximo: the day of the month it is due (1-31).
discountDays (integer (int64)): Days: days the early-payment discount lasts. Proximo: the day of the month it ends. Stored only.
discount (Amount or null): Early-payment discount percentage. Stored only.
cutoff (integer (int64)): Proximo only: documents posted after this day of the month are due a month later; 0 or less counts back from the end of the month.

Result

A billing term.

guid (Guid, required): Its GUID.
name (string, required): Its name; frozen copies share their parent's.
description (string, required): Description.
type (BillTermTypeWire or null): Days or proximo; absent for a term whose type was never set.
dueDays (integer (int64), required): Days until due, or the proximo due day.
discountDays (integer (int64), required): Discount days, or the proximo discount day.
discount (Amount, required): Discount percentage.
cutoff (integer (int64), required): Proximo cutoff day.
refcount (integer (int64), required): How many customers, vendors and documents use it (always 0 for a frozen copy).
invisible (boolean, required): True for frozen copies.
parent (Guid or null): The term it is a frozen copy of.
child (Guid or null): Its current frozen copy.