Inside a Loop (For Each) action that runs over a sales order’s line items, each loop action runs on the line item itself. Line-item custom fields are referenced by the field’s label, with a custom_field_ prefix. This article covers reading a field, setting a field, the {{ item.… }} placeholders, and what the Testing tab does.

Set a line-item custom field

  1. Go to Tools > Automation and click Create Rule.
  2. Choose your trigger, for example Order Created.
  3. Click Add Action and choose Loop (For Each). Leave Collection Name as orderItems to loop over the order’s line items.
  4. Optional: under Filter Items, click Add Filter to limit which lines are processed, for example SKU starts with CUSTOM-.
  5. Under Loop Actions, click Add Action and choose Update Field.
  6. In Field Name, search for and pick your field. Line-item custom fields appear as custom_field_, for example custom_field_Polybag. Labels with spaces work as-is.
  7. In New Value, enter the value. You can use placeholders such as {{ item.sku }} or {{ item.quantity }}.
  8. Click Create Automation and name the rule.

custom_field_ vs {{ item. }}

  • custom_field_ is a field key. Pick it in the Field Name of an Update Field action or a filter.
  • {{ item. }} is a placeholder you type inside a value. It reads standard line-item properties such as {{ item.sku }}, {{ item.quantity }} and {{ item.id }}. The parent order is available as {{ parent. }}, and {{ index }} is the position in the loop.
  • Don’t rely on {{ item.custom_field_ }} to read a custom field’s value inside a placeholder. To act on a custom field, use it in a filter or as the Update Field Field Name.

Reference a line-item custom field with custom_field_<Label>

The key is custom_field_ followed by the custom field's label exactly as it appears in your custom field setup. For a custom field labelled Polybag, the key is custom_field_Polybag.

The same key works in the places below:

  • Conditions inside a For Each loop. The inner conditions are evaluated against each line item. A field condition on custom_field_Polybag therefore checks that line's value. The alternative form custom_field["Field Label"] is also accepted by conditions, which helps if your label contains spaces.
  • Update Column (set a value) as a nested action. The nested action runs on the line item. Set the field to custom_field_<Label> and give it the new value, and the line item's custom field is saved.

Example: stamp a custom field on matching lines

  1. Add a For Each action and choose the order line items collection.
  2. Add an inner condition to limit which lines are processed, for example SKU starts with CUSTOM-.
  3. Add a nested Update Column action:
    • Field: custom_field_Polybag (replace Polybag with your label)
    • Value: the value you want to set. This can use {{ item.sku }} or {{ item.quantity }}.

custom_field_<Label> vs {{ item.<field> }}

These two do different jobs:

  • custom_field_<Label> is a field key. Use it in the Field box of a condition or Update Column action.
  • {{ item.<field> }} is a placeholder you type inside a value, such as an email subject or body. It reads standard line-item properties such as {{ item.sku }}, {{ item.quantity }} and {{ item.id }}. The parent order is available as {{ parent.<field> }}, and {{ index }} is the position in the loop.

Custom fields in {{ item.… }} placeholders: the placeholder reader looks for a built-in property or value on the line item, and custom fields are stored separately. I could not confirm that {{ item.custom_field_<Label> }} returns a value, so don't rely on it. To use a custom field's value, put it in a condition or in the Update Column Field (custom_field_<Label>). Then confirm the result in the Testing tab logs.

Do Testing-tab runs save values?

Yes. The Testing tab on an automation rule has no preview or dry-run mode. When you choose a record (Model Type and Model ID) and an Event Name and click Trigger Test, Luminous fires that event on the real record. The matching rules then run for real, and any Update Column actions are saved to the order and its line items.

To test safely:

  • Use a test or sandbox order.
  • Or build the rule with a condition that limits it to that order.
  • Then read the run log. It shows each loop item, whether it was skipped, and lines such as "Updated '' from '' to ''".

Good to know

  • If a nested action fails on one line, the loop carries on with the remaining lines.
  • Custom field labels must match an existing custom field. If no custom field has that label, the Update Column action fails and the log shows "No CustomField found with label …".

See also: How do I iterate over line items or map a field value to multiple fields in one automation rule? and Managing Line Item Custom Fields in Sales Orders.