Invoice

Need help? Ask Kademi

A bill issued to a customer, holding the line items being charged for and the date payment falls due. It is one kind of payment item list, sharing a table with quotes and purchase orders, and it moves through the statuses DRAFT, SENT, OVERDUE and PAID. An invoice number is allocated automatically when one is built without a number, and payments are recorded against the invoice as InvoicePaymentLink rows rather than as a field on the invoice itself.

Group: Database Entities

Extends: PaymentItemList

Properties

Property	Returns	Description
dueDate	`Date`	The date payment of this invoice falls due. Null if no due date has been set, and it is not copied when an invoice is duplicated, so a duplicate needs its own.
invoicePayments	`List<InvoicePaymentLink>`	The payments that have been applied to this invoice. This runs a query each time it is called rather than reading a mapped collection, so hold the result if you need it more than once.
invoiceStatus	`InvoiceStatus`	Where the invoice has got to, being DRAFT while it is being prepared, SENT once issued, OVERDUE once its due date has passed unpaid, and PAID once settled. New invoices built through the builder start as DRAFT.
totalDue	`BigDecimal`	The amount still owing, being the invoice total less everything paid against it. Queries the payment links each time it is called, and goes negative if the invoice has been overpaid.
totalPayments	`BigDecimal`	The sum of every payment applied to this invoice. Queries the payment links each time it is called, and returns zero when nothing has been paid.

Inherited from PaymentItemList

Properties

Property	Returns	Description
attachmentHash	`String`	Content hash of a document level file, such as the rendered PDF, used to fetch it from the blob store. This is separate from the attachments collection and may be null if no such file has been stored.
attachments	`List<PaymentItemListAttachment>`	The files attached to this document, such as a supplier's own PDF invoice. May be null if nothing has been attached.
cart	Cart	The shopping cart this document was raised from, if it came from an e-commerce order. Null for documents created directly, and lazily loaded.
country	`String`	Country to use for tax and shipping decisions, taken from the originating cart if it names one, otherwise from the first of the customer's addresses that names a country. Calculated on demand, not stored.
createdBy	`Profile`	The profile that created the document. The builder falls back to the current logged in user when none was given.
createdDate	`Date`	Date and time the document record was created in Kademi, which may differ from the issue date shown on the document.
currency	`String`	Currency the sub-total, tax and total amounts are expressed in, as a short code such as NZD. May be null if no currency was recorded against the document.
customer	`BaseEntity`	The party being charged, ie the profile or organisation this document is addressed to. Defaults to the profile that created the document.
deleted	`boolean`	Whether the document has been soft deleted. Deleted documents are excluded from the standard lookups but the row itself is retained.
deletedBy	`Profile`	The profile that soft deleted the document, or null if it has not been deleted.
deletedDate	`Date`	Date and time the document was soft deleted, or null if it has not been deleted.
deliveryAddressLine1	`String`	First line of the street address the goods on this document are to be delivered to.
deliveryAddressLine2	`String`	Second line of the delivery street address, such as a unit or building name.
deliveryAddressState	`String`	State, province or region of the delivery address, as free text.
deliveryAttentionTo	`String`	Name of the person the delivery should be addressed to, for the attention line on a shipping label.
deliveryCity	`String`	City or town of the delivery address.
deliveryCountry	`String`	Country of the delivery address, as free text rather than a validated country code.
deliveryNotes	`String`	Free-text instructions for the courier or warehouse, such as where to leave the parcel.
deliveryPostcode	`String`	Postcode or zip code of the delivery address.
description	`String`	Free-text notes about the document as a whole, separate from the per-line-item descriptions. May be null, and is limited to 5000 characters.
extraField1	`String`	First of three general purpose free-text fields, used to carry account specific data such as a customer's own reference. Also reachable by the name field1 through extraFieldValue.
extraField2	`String`	Second of three general purpose free-text fields. Also reachable by the name field2 through extraFieldValue.
extraField3	`String`	Third of three general purpose free-text fields. Also reachable by the name field3 through extraFieldValue.
id	`long`	Unique database identifier for this invoice, quote or purchase order.
issuedDate	`Date`	Date the document was issued to the customer, which is the date shown on the document itself. The builder sets it to the creation time if it was not supplied.
lineItems	`List<LineItem>`	The line items making up this document, each one a charged product or free-text item. May be null if no line items have been added yet, and is in no particular order, so use lineItemsSorted for a stable order.
number	`String`	The document number shown to the customer, such as an invoice or quote number. It is the lookup key for the document within the account, and the builder assigns a random UUID if none was supplied.
paymentItemListType	`String`	Which kind of document this is, as the string invoice, quote or purchasedOrder. Worked out on demand from the as-methods, so it is null on the base class.
subTotal	`BigDecimal`	Sum of the ex-tax amounts of all line items, in the document's currency. Recalculated by refreshPaymentItemListTotals whenever a line item is added.
tax	`BigDecimal`	Total tax charged across all line items, as an amount in the document's currency and not a rate. Tax rates themselves are held per line item.
title	`String`	Free-text display label for the document, shown to the customer. Unlike the number it carries no uniqueness guarantee, and may be null.
total	`BigDecimal`	The amount payable, ie the sub-total plus the tax, in the document's currency.
totalListPrice	`BigDecimal`	The undiscounted value of the document, calculated on demand. For product based line items this is the SKU's base cost times the quantity, and for other line items the persisted unit price times the quantity. Compare it with getTotal to see the effect of discounting.
totalQuantity	`BigDecimal`	Sum of the quantities across all line items, which is a count of units rather than a money amount. Calculated on demand and not stored.
vendor	`BaseEntity`	The party issuing this document, ie who is owed the money. The builder falls back to the profile that created the document if no vendor was set.

Methods

getId() · setOrganisation(Organisation organisation) · getLineItems() · getAttachments() · setAttachments(List<PaymentItemListAttachment> attachments) · getCustomer() · setCustomer(BaseEntity customer) · getNumber() · setNumber(String number) · getVendor() · setVendor(BaseEntity vendor) · getTitle() · setTitle(String title) · getCurrency() · setCurrency(String currency) · getDescription() · setDescription(String description) · getAttachmentHash() · setAttachmentHash(String attachmentHash) · getIssuedDate() · setIssuedDate(Date issuedDate) · getSubTotal() · setSubTotal(BigDecimal subTotal) · getTax() · setTax(BigDecimal tax) · getTotal() · setTotal(BigDecimal total) · getCreatedDate() · setCreatedDate(Date createdDate) · getCreatedBy() · setCreatedBy(Profile createdBy) · isDeleted() · setDeleted(boolean deleted) · getDeletedDate() · setDeletedDate(Date deletedDate) · getDeletedBy() · setDeletedBy(Profile deletedBy) · getDeliveryAddressLine1() · setDeliveryAddressLine1(String deliveryAddressLine1) · getDeliveryAddressLine2() · setDeliveryAddressLine2(String deliveryAddressLine2) · getDeliveryAddressState() · setDeliveryAddressState(String deliveryAddressState) · getDeliveryCity() · setDeliveryCity(String deliveryCity) · getDeliveryCountry() · setDeliveryCountry(String deliveryCountry) · getDeliveryPostcode() · setDeliveryPostcode(String deliveryPostcode) · getDeliveryAttentionTo() · setDeliveryAttentionTo(String deliveryAttentionTo) · getDeliveryNotes() · setDeliveryNotes(String deliveryNotes) · getCart() · setCart(Cart cart) · getExtraField1() · setExtraField1(String extraField1) · getExtraField2() · setExtraField2(String extraField2) · getExtraField3() · setExtraField3(String extraField3) · newLineItem() · refreshPaymentItemListTotals() · getTotalQuantity() · rowId() · lineItemsSorted() · asQuote() · asInvoice() · asPurchaseOrder() · extraFieldValue(String name) · setExtraField(String name, String value) · asPaymentItemList() · getCountry() · getTotalListPrice() · totalListPrice(Product p) · extraFieldValues() · getPaymentItemListType()

`getId()`

Returns: long

Unique database identifier for this invoice, quote or purchase order.

`setOrganisation(Organisation organisation)`

Returns: void

Sets the account holder organisation this payment item list belongs to.

Parameter	Description
`organisation`	the owning organisation

`getLineItems()`

Returns: List<LineItem>

The line items making up this document, each one a charged product or free-text item. May be null if no line items have been added yet, and is in no particular order, so use lineItemsSorted for a stable order.

`getAttachments()`

Returns: List<PaymentItemListAttachment>

The files attached to this document, such as a supplier's own PDF invoice. May be null if nothing has been attached.

`setAttachments(List<PaymentItemListAttachment> attachments)`

Returns: void

Replaces the collection of attached files held against this document.

Parameter	Description
`attachments`	the attachments to hold against this document

`getCustomer()`

Returns: BaseEntity

The party being charged, ie the profile or organisation this document is addressed to. Defaults to the profile that created the document.

`setCustomer(BaseEntity customer)`

Returns: void

Sets the party being charged by this document.

Parameter	Description
`customer`	the profile or organisation to address the document to

`getNumber()`

Returns: String

The document number shown to the customer, such as an invoice or quote number. It is the lookup key for the document within the account, and the builder assigns a random UUID if none was supplied.

`setNumber(String number)`

Returns: void

Sets the customer facing document number, which is also the lookup key within the account.

Parameter	Description
`number`	the document number to use

`getVendor()`

Returns: BaseEntity

The party issuing this document, ie who is owed the money. The builder falls back to the profile that created the document if no vendor was set.

`setVendor(BaseEntity vendor)`

Returns: void

Sets the party issuing this document and owed the money.

Parameter	Description
`vendor`	the profile or organisation issuing the document

`getTitle()`

Returns: String

Free-text display label for the document, shown to the customer. Unlike the number it carries no uniqueness guarantee, and may be null.

`setTitle(String title)`

Returns: void

Sets the free-text display label for the document.

Parameter	Description
`title`	the display title to show

`getCurrency()`

Returns: String

Currency the sub-total, tax and total amounts are expressed in, as a short code such as NZD. May be null if no currency was recorded against the document.

`setCurrency(String currency)`

Returns: void

Sets the currency code the document's amounts are expressed in.

Parameter	Description
`currency`	the currency code, such as NZD

`getDescription()`

Returns: String

Free-text notes about the document as a whole, separate from the per-line-item descriptions. May be null, and is limited to 5000 characters.

`setDescription(String description)`

Returns: void

Sets the free-text notes held against the document as a whole.

Parameter	Description
`description`	the description to store, up to 5000 characters

`getAttachmentHash()`

Returns: String

Content hash of a document level file, such as the rendered PDF, used to fetch it from the blob store. This is separate from the attachments collection and may be null if no such file has been stored.

`setAttachmentHash(String attachmentHash)`

Returns: void

Sets the content hash of the document level file held in the blob store.

Parameter	Description
`attachmentHash`	the content hash of the document's own file

`getIssuedDate()`

Returns: Date

Date the document was issued to the customer, which is the date shown on the document itself. The builder sets it to the creation time if it was not supplied.

`setIssuedDate(Date issuedDate)`

Returns: void

Sets the date the document was issued to the customer.

Parameter	Description
`issuedDate`	the issue date to record

`getSubTotal()`

Returns: BigDecimal

Sum of the ex-tax amounts of all line items, in the document's currency. Recalculated by refreshPaymentItemListTotals whenever a line item is added.

`setSubTotal(BigDecimal subTotal)`

Returns: void

Sets the ex-tax total of all line items. Normally maintained by refreshPaymentItemListTotals.

Parameter	Description
`subTotal`	the ex-tax total to store

`getTax()`

Returns: BigDecimal

Total tax charged across all line items, as an amount in the document's currency and not a rate. Tax rates themselves are held per line item.

`setTax(BigDecimal tax)`

Returns: void

Sets the total tax amount for the document. Normally maintained by refreshPaymentItemListTotals.

Parameter	Description
`tax`	the total tax amount to store

`getTotal()`

Returns: BigDecimal

The amount payable, ie the sub-total plus the tax, in the document's currency.

`setTotal(BigDecimal total)`

Returns: void

Sets the total payable amount. Normally maintained by refreshPaymentItemListTotals.

Parameter	Description
`total`	the total payable amount to store

`getCreatedDate()`

Returns: Date

Date and time the document record was created in Kademi, which may differ from the issue date shown on the document.

`setCreatedDate(Date createdDate)`

Returns: void

Sets the date and time the document record was created.

Parameter	Description
`createdDate`	the creation timestamp to record

`getCreatedBy()`

Returns: Profile

The profile that created the document. The builder falls back to the current logged in user when none was given.

`setCreatedBy(Profile createdBy)`

Returns: void

Sets the profile recorded as having created the document.

Parameter	Description
`createdBy`	the creating profile

`isDeleted()`

Returns: boolean

Whether the document has been soft deleted. Deleted documents are excluded from the standard lookups but the row itself is retained.

`setDeleted(boolean deleted)`

Returns: void

Marks the document as soft deleted or restores it.

Parameter	Description
`deleted`	true to soft delete the document, false to restore it

`getDeletedDate()`

Returns: Date

Date and time the document was soft deleted, or null if it has not been deleted.

`setDeletedDate(Date deletedDate)`

Returns: void

Sets the date and time the document was soft deleted.

Parameter	Description
`deletedDate`	the deletion timestamp to record

`getDeletedBy()`

Returns: Profile

The profile that soft deleted the document, or null if it has not been deleted.

`setDeletedBy(Profile deletedBy)`

Returns: void

Sets the profile recorded as having soft deleted the document.

Parameter	Description
`deletedBy`	the deleting profile

`getDeliveryAddressLine1()`

Returns: String

First line of the street address the goods on this document are to be delivered to.

`setDeliveryAddressLine1(String deliveryAddressLine1)`

Returns: void

Sets the first line of the delivery street address.

Parameter	Description
`deliveryAddressLine1`	the first delivery address line

`getDeliveryAddressLine2()`

Returns: String

Second line of the delivery street address, such as a unit or building name.

`setDeliveryAddressLine2(String deliveryAddressLine2)`

Returns: void

Sets the second line of the delivery street address.

Parameter	Description
`deliveryAddressLine2`	the second delivery address line

`getDeliveryAddressState()`

Returns: String

State, province or region of the delivery address, as free text.

`setDeliveryAddressState(String deliveryAddressState)`

Returns: void

Sets the state, province or region of the delivery address.

Parameter	Description
`deliveryAddressState`	the delivery state or region

`getDeliveryCity()`

Returns: String

City or town of the delivery address.

`setDeliveryCity(String deliveryCity)`

Returns: void

Sets the city or town of the delivery address.

Parameter	Description
`deliveryCity`	the delivery city

`getDeliveryCountry()`

Returns: String

Country of the delivery address, as free text rather than a validated country code.

`setDeliveryCountry(String deliveryCountry)`

Returns: void

Sets the country of the delivery address.

Parameter	Description
`deliveryCountry`	the delivery country

`getDeliveryPostcode()`

Returns: String

Postcode or zip code of the delivery address.

`setDeliveryPostcode(String deliveryPostcode)`

Returns: void

Sets the postcode or zip code of the delivery address.

Parameter	Description
`deliveryPostcode`	the delivery postcode

`getDeliveryAttentionTo()`

Returns: String

Name of the person the delivery should be addressed to, for the attention line on a shipping label.

`setDeliveryAttentionTo(String deliveryAttentionTo)`

Returns: void

Sets the name the delivery should be addressed to.

Parameter	Description
`deliveryAttentionTo`	the delivery attention-to name

`getDeliveryNotes()`

Returns: String

Free-text instructions for the courier or warehouse, such as where to leave the parcel.

`setDeliveryNotes(String deliveryNotes)`

Returns: void

Sets the free-text delivery instructions for the courier or warehouse.

Parameter	Description
`deliveryNotes`	the delivery notes

`getCart()`

Returns: Cart

The shopping cart this document was raised from, if it came from an e-commerce order. Null for documents created directly, and lazily loaded.

`setCart(Cart cart)`

Returns: void

Links this document to the shopping cart the order came from.

Parameter	Description
`cart`	the originating cart

`getExtraField1()`

Returns: String

First of three general purpose free-text fields, used to carry account specific data such as a customer's own reference. Also reachable by the name field1 through extraFieldValue.

`setExtraField1(String extraField1)`

Returns: void

Sets the first general purpose free-text field.

Parameter	Description
`extraField1`	the value to store in the first extra field

`getExtraField2()`

Returns: String

Second of three general purpose free-text fields. Also reachable by the name field2 through extraFieldValue.

`setExtraField2(String extraField2)`

Returns: void

Sets the second general purpose free-text field.

Parameter	Description
`extraField2`	the value to store in the second extra field

`getExtraField3()`

Returns: String

Third of three general purpose free-text fields. Also reachable by the name field3 through extraFieldValue.

`setExtraField3(String extraField3)`

Returns: void

Sets the third general purpose free-text field.

Parameter	Description
`extraField3`	the value to store in the third extra field

`newLineItem()`

Returns: LineItem

Creates a new, empty line item, adds it to this document and links it back to this document. The line item is not saved and the totals are not refreshed, so set the amounts on the returned line item and then call refreshPaymentItemListTotals.

`refreshPaymentItemListTotals()`

Returns: void

Recalculates the document's sub-total and tax by summing the corresponding amounts across every line item, then sets the total to the sub-total plus the tax. Call it after changing line items so the stored totals match. It reads the line items collection directly, so the document must have one.

`getTotalQuantity()`

Returns: BigDecimal

Sum of the quantities across all line items, which is a count of units rather than a money amount. Calculated on demand and not stored.

`rowId()`

Returns: Long

The row's identifier as used by the generic relational reporting layer, which is the same value as getId.

`lineItemsSorted()`

Returns: List<LineItem>

The document's line items in a stable order, sorted ascending by line item id so they appear in the order they were added. Returns an empty list rather than null when there are no line items.

`asQuote()`

Returns: Quote

Narrows this document to a quote. Returns null on the base class and on any subclass that is not a quote, so use it to test which kind of document you are holding.

`asInvoice()`

Returns: Invoice

Narrows this document to an invoice. Returns null on the base class and on any subclass that is not an invoice, so use it to test which kind of document you are holding.

`asPurchaseOrder()`

Returns: PurchaseOrder

Narrows this document to a purchase order. Returns null on the base class and on any subclass that is not a purchase order, so use it to test which kind of document you are holding.

`extraFieldValue(String name)`

Returns: String

Reads one of the three general purpose extra fields by name. Only the names field1, field2 and field3 are recognised; anything else throws.

Parameter	Description
`name`	the extra field to read, one of field1, field2 or field3

`setExtraField(String name, String value)`

Returns: void

Writes one of the three general purpose extra fields by name. Only the names field1, field2 and field3 are recognised; anything else throws, and a null name is ignored.

Parameter	Description
`name`	the extra field to write, one of field1, field2 or field3
`value`	the value to store in that field

`asPaymentItemList()`

Returns: PaymentItemList

Narrows this sale to a payment item list, which for this class is always itself. It lets code holding any kind of sale check whether it is backed by an invoice, quote or purchase order.

`getCountry()`

Returns: String

Country to use for tax and shipping decisions, taken from the originating cart if it names one, otherwise from the first of the customer's addresses that names a country. Calculated on demand, not stored.

`getTotalListPrice()`

Returns: BigDecimal

The undiscounted value of the document, calculated on demand. For product based line items this is the SKU's base cost times the quantity, and for other line items the persisted unit price times the quantity. Compare it with getTotal to see the effect of discounting.

`totalListPrice(Product p)`

Returns: BigDecimal

The undiscounted value of just the line items for the given product, calculated the same way as getTotalListPrice. Line items with no unit cost are skipped and logged.

Parameter	Description
`p`	the product to restrict the calculation to

`extraFieldValues()`

Returns: Map<String,String>

The document's extra fields as a map of field name to value, resolved by the payment manager so the field labels configured for the account are used rather than the raw field1 to field3 names.

`getPaymentItemListType()`

Returns: String

Which kind of document this is, as the string invoice, quote or purchasedOrder. Worked out on demand from the as-methods, so it is null on the base class.

Methods

`getInvoiceStatus()`

Returns: InvoiceStatus

Where the invoice has got to, being DRAFT while it is being prepared, SENT once issued, OVERDUE once its due date has passed unpaid, and PAID once settled. New invoices built through the builder start as DRAFT.

`setInvoiceStatus(InvoiceStatus invoiceStatus)`

Returns: void

Sets where the invoice has got to. Changing this does not itself send or reconcile anything.

Parameter	Description
`invoiceStatus`	the new invoice status

`getDueDate()`

Returns: Date

The date payment of this invoice falls due. Null if no due date has been set, and it is not copied when an invoice is duplicated, so a duplicate needs its own.

`setDueDate(Date dueDate)`

Returns: void

Sets the date payment of this invoice falls due.

Parameter	Description
`dueDate`	the date payment is due

`getInvoicePayments()`

Returns: List<InvoicePaymentLink>

The payments that have been applied to this invoice. This runs a query each time it is called rather than reading a mapped collection, so hold the result if you need it more than once.

`getTotalPayments()`

Returns: BigDecimal

The sum of every payment applied to this invoice. Queries the payment links each time it is called, and returns zero when nothing has been paid.

`getTotalDue()`

Returns: BigDecimal

The amount still owing, being the invoice total less everything paid against it. Queries the payment links each time it is called, and goes negative if the invoice has been overpaid.

To get full access to the Kademi Hub existing customers can login here, or new customers can register here.