Invoice Item Schema
Individual line items and grouped charges within invoices
The Invoice Item schema defines the structure and properties of invoice item objects in the Payload API. Invoice items represent individual line items or grouped charges within invoices, supporting hierarchical organization with quantity, pricing, and detailed line item ordering for professional invoice presentation.
Invoice Item Object Properties
Complete reference for all properties available in the Invoice Item schema
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
descriptionstring
Text description of this invoice item. This appears on the invoice and helps identify what the charge is for. Examples include "Monthly subscription fee", "Setup charge", "Product: Widget Pro", or "Consulting hours". Clear descriptions help customers understand their invoices and reduce payment disputes and support inquiries.
Max length: 128
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: item)
Pattern:
^item_[A-Za-z0-9]+$invoice_id ID of Invoicestring
The unique identifier of the invoice that this item belongs to. Links the item to its parent invoice, which determines billing, payment, and payer information. Required for all invoice items. (ID prefix: inv)
Pattern:
^inv_[A-Za-z0-9]+$item_groupobject
Container for grouping multiple related line items together. Required when type is "item_group". Use item groups to organize charges on invoices for better readability and structure, such as grouping all products, services, or fees into separate sections. Hidden when type is not "item_group".
Required if:
type=item_groupitemsInvoiceItemarray
List of line items that belong to this item group. Each item in this list must have type "line_item" and will be nested under this group for organizational purposes. Expanded by default when retrieving the item group. Use this to organize related charges together on an invoice (e.g., grouping all shipping charges or all product line items).
line_itemobject
Detailed pricing information for a line item charge. Required when type is "line_item". Contains the unit value, quantity, and automatically calculated total. Use this for individual charges on an invoice, such as product prices, service fees, or usage charges. Hidden when type is not "line_item".
Required if:
type=line_itemqtynumber (double)
The quantity or number of units for this line item. Multiplied by the value to calculate the total charge. For example, if value is 10.00 and qty is 3, the total would be 30.00. Defaults to 1 if not specified.
totalnumber (double)Read-only
The calculated total amount for this line item (value * qty), rounded to 2 decimal places. This field is read-only and automatically computed. Represents the final charge that will be applied to the invoice for this line item.
valuenumber (double)
The unit amount or rate for this line item. If value_units is "number", this is the price per unit. If value_units is "percentage", this is the percentage rate (e.g., 5.5 for 5.5%). The total charge is calculated as value * qty. Required for line items.
value_unitsenum[string]
Specifies how the value should be interpreted. Set to "number" for fixed amounts (e.g., $10.00 per item) or "percentage" for percentage-based charges (e.g., 5% of a base amount). Determines how the line item total is calculated.
Values:
percentage, numberline_numberinteger (int64)
Numeric value that determines the display order of line items on the invoice. Lower numbers appear first. Use this to control the presentation order of charges, such as showing products before shipping, or grouping related items together. If not specified, items are ordered by creation time. Useful for ensuring consistent, professional invoice formatting.
modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
objectenum[string]Read-only
String representing the object type for this resource.
Values:
invoice_itemparent_item_group_id ID of InvoiceItemstring
The unique identifier of the parent item group that this line item belongs to. If set, this line item is nested within an item_group for organizational purposes. If null, this item is a top-level item on the invoice. Only applicable when this item has type "line_item". (ID prefix: item)
Pattern:
^item_[A-Za-z0-9]+$typeenum[string]Required
The type of invoice item. Must be either "line_item" (a single charge with amount and quantity) or "item_group" (a container for grouping multiple line items together). The type determines which fields are required and how the item is structured.
Values:
line_item, item_group