record_line_add()

Append one line item to a parent record's sub-table.

Syntax

record_line_add(table, recordId, subtable, row, opts?)

Parameters

Name	Type	Required	Description
`table`	string or number	yes	The parent table's name, its database table name, or its numeric table id. Read the id from `$table` at run time; never type one into your code, because table ids change when a workspace is copied.
`recordId`	int	yes	The parent record's primary key.
`subtable`	string or number	yes	The line-item table to write. It must belong to this parent.
`row`	array	yes	The new line's field values, keyed by field id.
`opts`	array	no	Options. `["silent" => true]` suppresses notifications to the record's followers.

Returns

The parent record as it is after the write, in the same shape as record_get(). Not the new line.

That is deliberate: adding a line changes the parent's rollup totals, so the parent is what you need next. Assign it back to your variable and later steps read the new total:

$record = record_line_add("invoices", $record["_meta"]["id"], "invoice_lines", [
    "label" => "Install",
    "qty" => 2,
    "price" => "75.00"
]);

The visual builder's Add Line Item step does this assignment for you.

Example

$record = record_line_add("invoices", $record["_meta"]["id"], "invoice_lines", [
    "label" => "Install",
    "qty" => 2,
    "price" => "75.00"
]);
sys_log("Invoice now totals " . $record["price_total"]);

Example output

["id" => 42, "title" => "INV-1001", "price_total" => "150.00", "_meta" => ["id" => 42, "title" => "INV-1001"]]

Notes

The parent and every line commit in one transaction. If the new line is rejected (a required field, a validation rule, the sub-table's maximum line count), nothing is written at all.
Every other line on the record is left exactly as it was, including its id.
The new line's own id is not returned. Fetch it with records_related() if you need it.
Calculation columns on the line and rollup fields on the parent are computed for you; passing them is ignored.
The write is recorded in the parent's activity history but does not trigger other automations.