Invoice items
The invoice items object contains information about items on an invoice.
Last updated
The invoice items object contains information about items on an invoice.
Last updated
When printed, an items list will consist of a group, the items inside the group, and then a subtotal row.
To build this in Liquid, you'd use a similar structure:
There's no subtotal row in the web interface. Subtotal items are included in the invoice items object to make it easy to include and style a subtotal row. A subtotal item iterates after a group and its items have iterated. They're purely informational rows, so most of the objects below will return "Liquid error" when used with a subtotal item.
Invoice items may depend slightly differently depending on how an invoice was generated. An invoice can be created manually, from an opportunity, or from a project.
When created from an opportunity or project, you can choose to itemize, or create summed lines for opportunity groups, product groups, or opportunities. Keep this in mind when building custom documents: some objects might make sense when itemized, but not when grouped by opportunity.
Invoice item objects are always accessed within a forloop that iterates for each item.
The item
object can be accessed in document layouts created against the following modules:
Returns invoice items for invoices linked to a particular opportunity.
Returns invoice items for invoices linked to a particular organization.
Returns invoice items for active invoices linked to a particular organization.
The item
object can be accessed in discussion templates created against the following modules:
Returns invoice items for invoices linked to a particular opportunity
Returns invoice taxes for invoices linked to a particular organization.
Returns invoice items for active invoices linked to a particular organization.
accessory_is_default?
Returns true
if an invoice item is an accessory and the accessory’s inclusion type is “Default”.
accessory_is_mandatory?
Returns true
if an invoice item is an accessory and the accessory’s inclusion type is “Mandatory”.
accessory_is_optional?
Returns true
if an invoice item is an accessory and the accessory’s inclusion type is “Optional”.
accessory_mode_is_accessory?
Returns true
if an invoice item is an accessory and the accessory’s mode is “Accessory”.
accessory_mode_is_component?
Returns true
if an invoice item is an accessory and the accessory’s mode is “Component”.
accessory_mode_is_safety?
Returns true
if an invoice item is an accessory and the accessory’s mode is “Safety”.
accessory_mode_name
Returns the accessory’s mode name where an invoice item is an accessory; blank otherwise.
accessory
component
safety item
charge_ends_at
Returns the charging end date for an invoice item. Generally used for invoice items with transaction types of rental or service.
charge_excluding_tax_total
Returns an invoice item charge total excluding tax.
Use the currency filter or a number filter to change the way that the number is formatted.
charge_including_tax_total
Returns an invoice item charge total including tax.
charge_starts_at
Returns the charging start date for an invoice item. Generally used for invoice items with transaction types of rental or service.
charge_total
Returns an invoice item charge total.
This may be including or excluding tax depending on the value of the “Catalog Prices” setting in System Preferences.
chargeable_days
Returns the number of chargeable days for an invoice item.
For service items, the value of the “Rate Quantity” field is returned. The rate type may be hour or distance.
For sale items, returns 0.0
.
charging_periods
Returns charging period objects for an invoice item.
children
Returns invoice item objects for an invoice item.
When an item is an item, this will return accessories .
When the item is a group, this will return items within that group.
The children
object only returns objects that are the next level deep in the tree. For example, accessories on accessories aren't returned.
depth
Returns the depth of an item in the tree. An item’s depth is determined by how it is nested under items.
depth_padding
Returns the depth padding for an invoice item. Generally used to apply an inline style to a table cell in HTML so that items appear nested.
Increments in multiples of 16.
description
Returns an invoice item’s description.
discount_amount
Returns the amount of discount applied to an invoice item.
Returns 0.0
for groups and subtotals.
discount_percent
Returns the percentage discount applied to an invoice item.
Returns 0.0
for groups and subtotals.
discounted_price
Returns an invoice item’s price after discount.
has_child_items?
Returns true
if an invoice
item has children items; false
otherwise. Generally used for detecting if an invoice item has accessories.
has_discount?
Returns true
if an invoice item has a discount applied; false
otherwise.
Where an invoice item has a negative discount applied, has_discount
will return false
. For example, -50% would increment the charge total by 50% so has_discount
will return false
.
id
Returns an invoice item ID.
The ID is an internal reference for a record. It's not exposed in our web interface.
invoiceable_item_description
Returns the description of the record that this invoice item is linked to.
When invoicing by item, this will return the description set against the product or service records.
When invoicing by product group, this will return the product group description set in System Setup > Product Groups.
When invoicing by opportunity, this will return the (internal) description set against the opportunity.
Returns blank for part invoice line items.
invoiceable_name
Returns the name of the record that this invoice item is linked to.
When invoicing by item, this will return the name of the product or service.
When invoicing by product group, this will return the product group name set in System Setup > Product Groups.
When invoicing by opportunity, this will return the name set against the opportunity.
The invoiceable_name
should generally be the same as the item name
; it may be different if you’ve changed the name of a record after it’s been added to an invoice.
For part invoice line items, returns the value of the “Final Invoice Credit Text” in System Preferences. This is used when your final invoice is created at a later point.
invoiceable_object
Returns opportunity item, product, service, or opportunity objects for an invoice item.
The type of object depends on an invoice item’s invoiceable type.
Invoiceable type
Object
Opportunity
opportunity
Opportunity Item
opportunity item
Item
product or service
Items with the invoiceable type Item
may be part invoice line items; be sure to cater for this in your code.
invoiceable_type
Returns the type of an invoice item. Generally describes the circumstances why an invoice item was created.
Invoiceable type
Description
Opportunity
An item created from an invoice grouped by opportunity.
Opportunity Item
An item created from an invoice grouped by opportunity item.
Product Group
An item created from an invoice grouped by product group.
Surcharge
An item created for an opportunity item surcharge total.
OpportunityDeal
An item created for an opportunity or opportunity group deal price.
Item
An item created by adding it directly to an invoice, or any other item.
There's no space between OpportunityDeal
is_accessory?
Returns true
if an invoice item is an accessory; false
otherwise.
is_deal_item?
Returns true
if an invoice item is a deal item, i.e. it is an item created with a charge total for a deal; false
otherwise.
Deal items have a red ”Deal Price” label in the list.
is_group?
Returns true
if an invoice item is a group; false
otherwise.
is_in_deal?
Returns true
if an invoice item is inside a deal, i.e. if it is an informational line included underneath a deal price line on an invoice; false
otherwise.
An item that is_in_deal?
will always be nested under an item that is_deal_item?
.
is_item?
Returns true
if an invoice item is an item; false
otherwise.
is_principal?
Returns true
if an invoice item has accessory items nested underneath it; false
otherwise.
is_product?
Returns true
if an invoice item is linked to a product record; false
otherwise.
is_rental?
Returns true
if an invoice item is a rental charge, i.e. its transaction type is "Rental"; false
otherwise.
is_sale?
Returns true
if an invoice item is for a sale charge, i.e. its transaction type is "Sale"; false
otherwise.
is_service?
Returns true
if an invoice item is for a service charge, i.e. its transaction type is "Service"; false
otherwise.
This doesn't determine necessarily whether an invoice item is linked to a service record; a text item may have the transaction type "Service".
is_service_item?
Returns true
if an invoice item is linked to a service record; false
otherwise.
is_subtotal?
Returns true
if an invoice item is a group item's subtotal; false
otherwise.
Subtotal rows are informational only and many invoice item objects will print "Liquid error: internal" rather than return blank
or false
.
is_text_item?
Returns true
if an invoice item is a text item; false
otherwise.
name
Returns an invoice item's name.
order
Returns opportunity objects for the opportunity that an invoice item is related to.
price
Returns an invoice item's price without discount.
price_unit
Returns an invoice item's price unit name.
The price unit name output depends on the rental charge used. Some common examples:
Daily
Weekly
Per period
Each
project_name
Returns the name of the project that an invoice item is related to. Generally the name of the project linked to the opportunity that was the origin of an invoice item.
quantity
Returns the quantity of an invoice item.
rate_definition_name
Returns the rate definition name for an invoice item where the item is a rental.
Returns blank for sales, services, surcharges, and group items.
service_unit_name
Returns the service unit name for an invoice item.
Day
Days
Hour
Hours
miles
km
source_name
Returns the name of the source of an invoice item. Generally the name of the opportunity that was the origin of an invoice item.
subtotal
Returns the subtotal amount for an invoice item group.
Subtotal rows are informational only. This will only return a value for subtotal rows. This will match the charge_total
of the corresponding invoice item group.
subtotal_name
Returns the subtotal name for an invoice item group.
Subtotal rows are informational only. This will only return a value for subtotal rows. This will match the name
of the corresponding invoice item group.
tax_class_name
Returns the tax class name against an invoice item. This is set against the product or service record, or when creating a text item.
tax_total
Returns the tax total for an invoice item.
transaction_type_name
Returns the transaction type name for an invoice item.
Rental
Sale
Service
unit_charge
Returns the unit charge for an invoice item.
The unit charge is the price for one unit of an invoice item.
unit_charge_amount
Returns the unit charge for an invoice item excluding discount.
The unit charge is the price for one unit of an invoice item.
use_chargeable_days
Returns true
if an invoice item has overriden chargeable days.
This will be the case where the source opportunity of an invoice has the "Chargeable Days" toggle set to YES.