Method

invoice.addEntry

Add a line to an unposted document (and optionally to an order).

Adds a line to an unposted document, and optionally to an open order too (customer invoices only). A line has a description, a quantity, a price and an income account (invoices) or expense account (bills and vouchers).

Anything you leave out is filled in as GnuCash's entry register would: the price from the job's rate, the discount from the customer, the tax table from the customer, vendor or the book's default, tax included from the owner. So a line on a customer's invoice can come back with a discount and a tax table you never asked for.

Fields that GnuCash's register has no column for on a kind of document are refused: discounts on bills, billable and billTo on invoices, tax settings on vouchers. So are accounts the register does not offer: A/R, A/P, bank, cash, equity and placeholder accounts, an expense account on an invoice or an income account on a bill. On a credit note, quantity is the quantity as printed, and is stored negated.

Examples

{"jsonrpc":"2.0","id":1,"method":"invoice.addEntry","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","description":"Design","quantity":"4","account":"Income"}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "…",
    "description": "Design",
    "quantity": {
      "num": "4",
      "denom": "1"
    },
    "invoicePrice": {
      "num": "9000",
      "denom": "100"
    },
    "discount": {
      "num": "5",
      "denom": "1"
    },
    "discountType": "percent",
    "invoiceTaxTable": "489200ce534b46379dd206e300012248",
    "…": "…"
  }
}

red-ale exec --book book.gnucash invoice.addEntry '{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","description":"Design","quantity":"4","account":"Income"}'

{
  "guid": "…",
  "description": "Design",
  "quantity": {
    "num": "4",
    "denom": "1"
  },
  "invoicePrice": {
    "num": "9000",
    "denom": "100"
  },
  "discount": {
    "num": "5",
    "denom": "1"
  },
  "discountType": "percent",
  "invoiceTaxTable": "489200ce534b46379dd206e300012248",
  "…": "…"
}

{"name":"invoice.addEntry","arguments":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","description":"Design","quantity":"4","account":"Income"}}

{
  "structuredContent": {
    "guid": "…",
    "description": "Design",
    "quantity": {
      "num": "4",
      "denom": "1"
    },
    "invoicePrice": {
      "num": "9000",
      "denom": "100"
    },
    "discount": {
      "num": "5",
      "denom": "1"
    },
    "discountType": "percent",
    "invoiceTaxTable": "489200ce534b46379dd206e300012248",
    "…": "…"
  }
}

Posted documents are closed to new lines:

{"jsonrpc":"2.0","id":1,"method":"invoice.addEntry","params":{"invoice":"aa210b7131de44c48b8513cd27c00e95","description":"Late extra","quantity":"1","price":"10","account":"Income"}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "help": "error/conflict"
    }
  }
}

red-ale exec --book book.gnucash invoice.addEntry '{"invoice":"aa210b7131de44c48b8513cd27c00e95","description":"Late extra","quantity":"1","price":"10","account":"Income"}'

{
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "help": "error/conflict"
    }
  }
}

{"name":"invoice.addEntry","arguments":{"invoice":"aa210b7131de44c48b8513cd27c00e95","description":"Late extra","quantity":"1","price":"10","account":"Income"}}

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "…",
      "data": {
        "help": "error/conflict"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of invoice.addEntry.

• invoice (Guid, required): The unposted document.
• order (Guid or null): Also put the line on this open order. Customer invoices only: order lines use the invoice side, as GnuCash's order ledger does.
• date (Date or null): The line's date; stored as noon local time, as GnuCash's register does. Defaults to today.
• description (string or null): Description.
• action (string or null): Action: a free unit label such as "Hours".
• notes (string or null): Notes.
• quantity (Amount or null): Quantity, as printed on the document; stored negated on a credit note.
• account (AccountRef or null): The income account (invoices) or expense account (bills, vouchers); null for none.
• price (Amount or null): Unit price. A new line on a job's document defaults to the job's rate.
• discount (Amount or null): Invoices only: the discount, a percentage or an amount. Defaults to the customer's discount.
• discountType (AmountTypeWire or null): Invoices only: whether the discount is a percentage or an amount.
• discountHow (DiscountHowWire or null): Invoices only: when the discount applies relative to tax.
• taxable (boolean or null): Invoices and bills: the line is taxed. Defaults to true when a tax table applies.
• taxIncluded (boolean or null): Invoices and bills: the price includes tax. Defaults from the customer's or vendor's setting.
• taxTable (TaxTableRef or null): Invoices and bills: the tax table, by GUID or name; null for none. Defaults to the owner's table when it overrides, else the book's default.
• billable (boolean or null): Bills and vouchers: the cost is to be invoiced on to billTo.
• billTo (Guid or null): Bills and vouchers: the customer or job to invoice the cost to; null for none.
• payment (PaymentWire or null): Vouchers only: cash (the employee paid) or card (the company card paid).

Result

A line. Both sides are shown; the one its document uses is invoice* for customer invoices and bill* for bills and vouchers.

• guid (Guid, required): A GUID: 32 hexadecimal digits.
• date (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix.
• dateEntered (Timestamp, required): An instant, RFC 3339; written in UTC with a Z suffix.
• description (string, required)
• action (string, required)
• notes (string, required)
• quantity (Amount, required): As stored: negated on a credit note.
• documentQuantity (Amount, required): As printed on the document.
• invoice (Guid or null): The customer invoice it is on.
• bill (Guid or null): The bill or voucher it is on.
• order (Guid or null): The order it is on.
• invoiceAccount (Guid or null)
• invoicePrice (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.
• discount (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.
• discountType (AmountTypeWire, required): Percentage or fixed amount.
• discountHow (DiscountHowWire, required): When a discount applies relative to tax.
• invoiceTaxable (boolean, required)
• invoiceTaxIncluded (boolean, required)
• invoiceTaxTable (Guid or null)
• billAccount (Guid or null)
• billPrice (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.
• billTaxable (boolean, required)
• billTaxIncluded (boolean, required)
• billTaxTable (Guid or null)
• billable (boolean, required)
• billTo (OwnerInfo or null)
• payment (PaymentWire, required): How an employee paid an expense.