To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Base class for the money documents a payment item list can be: an invoice, a quote or a purchase order. Holds the parties (customer and vendor), the currency, the line items and their rolled up sub-total, tax and total, a delivery address, and up to three free-text extra fields. It cannot be instantiated on its own; the concrete subclasses are distinguished by the PaymentItemListType discriminator column, and asInvoice, asQuote and asPurchaseOrder tell you which one you are holding. A payment item list may optionally be linked to the cart the order came from.
Group: Database Entities
Implements: Serializable, ISale, Relational
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.
© 2025 Kademi Ltd