Method

invoice.create

Create an invoice, bill or expense voucher; the owner decides which.

Creates an unposted document: an invoice, a bill or an expense voucher, with no lines yet. The owner decides which: a customer gives an invoice, a vendor a bill, an employee an expense voucher, and a job gives the kind of its owner. Add lines with invoice.addEntry, then post it with invoice.post.

The document takes its owner's currency and billing term (give terms: null for none), and its number from the counter of its kind (gncInvoice, gncBill or gncExpVoucher) unless you give id. A number taken is never given back, even if the document is later deleted. creditNote: true makes a credit note, which cannot be changed afterwards; it also sets the book feature Credit Notes, which older GnuCash versions do not know, so they will refuse the book.

Examples

{"jsonrpc":"2.0","id":1,"method":"invoice.create","params":{"owner":"5b22073fa4e34411b07c14a77147ce6b","billingId":"PO-5"}}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "guid": "…",
    "id": "000003",
    "type": "invoice",
    "posted": false,
    "terms": "3416d941790749378beeb338b8357a72",
    "billingId": "PO-5",
    "entryCount": 0,
    "entries": [],
    "…": "…"
  }
}

{"jsonrpc":"2.0","id":2,"method":"invoice.create","params":{"owner":"9697710198334d558a9bfde219bb1e41"}}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "guid": "…",
    "id": "000002",
    "type": "bill",
    "posted": false,
    "…": "…"
  }
}

red-ale exec --book book.gnucash --script - <<'EOF'
invoice.create {"owner":"5b22073fa4e34411b07c14a77147ce6b","billingId":"PO-5"}
invoice.create {"owner":"9697710198334d558a9bfde219bb1e41"}
EOF

[
  {
    "guid": "…",
    "id": "000003",
    "type": "invoice",
    "posted": false,
    "terms": "3416d941790749378beeb338b8357a72",
    "billingId": "PO-5",
    "entryCount": 0,
    "entries": [],
    "…": "…"
  },
  {
    "guid": "…",
    "id": "000002",
    "type": "bill",
    "posted": false,
    "…": "…"
  }
]

{"name":"invoice.create","arguments":{"owner":"5b22073fa4e34411b07c14a77147ce6b","billingId":"PO-5"}}

{
  "structuredContent": {
    "guid": "…",
    "id": "000003",
    "type": "invoice",
    "posted": false,
    "terms": "3416d941790749378beeb338b8357a72",
    "billingId": "PO-5",
    "entryCount": 0,
    "entries": [],
    "…": "…"
  }
}

{"name":"invoice.create","arguments":{"owner":"9697710198334d558a9bfde219bb1e41"}}

{
  "structuredContent": {
    "guid": "…",
    "id": "000002",
    "type": "bill",
    "posted": false,
    "…": "…"
  }
}

Effect: write, on the Book.

Params

Params of invoice.create. owner is required.

• 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.