Billing Item Schema
Line items and grouped charges for recurring billing schedules
The Billing Item schema defines the structure and properties of billing item objects in the Payload API. Billing items represent individual line items or grouped charges within billing schedules, supporting both simple line items and hierarchical item groups with quantity, pricing, and date-based billing controls.
Billing Item Object Properties
Complete reference for all properties available in the Billing Item schema
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
billing_schedule_id ID of BillingSchedulestring
The unique identifier of the billing schedule that this item belongs to. Links the item to its parent billing schedule, which determines when and how often this item will be billed. (ID prefix: bscd)
Pattern:
^bscd_[A-Za-z0-9]+$created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
descriptionstring
Text description of this billing item. This appears on invoices and helps identify what the charge is for. Examples include "Monthly subscription fee", "Setup charge", "Usage overage", or "Product: Widget Pro". Clear descriptions help customers understand their invoices and reduce payment disputes.
Max length: 128
end_datestring (date)
The date when this billing item expires and stops appearing on generated invoices. After this date, the item will no longer be included in new invoices. Leave empty for indefinite charges. Use this for time-limited charges like promotional pricing, temporary fees, or service periods with defined end dates.
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: bcrg)
Pattern:
^bcrg_[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_groupitemsBillingItemarray
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 a billing schedule, 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.
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, numbermodified_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:
billing_itemparent_item_group_id ID of BillingItemstring
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 billing schedule. Only applicable when this item has type "line_item". (ID prefix: bcrg)
Pattern:
^bcrg_[A-Za-z0-9]+$start_datestring (date)
The date when this billing item becomes active and starts appearing on generated invoices. Items will not be included in invoices created before this date. Use this to schedule charges to begin at a future date, such as when a service starts or a product is delivered. Useful for pro-rated billing or time-limited charges.
typeenum[string]Required
The type of billing 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