Adding Line Items

The add action inserts new items into a collection — most often, new line items into an order. Inside the action, a set statement on item configures the new item. Once added, the new line is part of the order from that point forward.

add 1 item to order_lines in order
  set item.sku to "GIFT-WRAP"
  set item.unit_price to 0.0
  set item.quantity to 1
end

Reads as: add 1 item to the order_lines collection on the order, with SKU “GIFT-WRAP” and the other fields shown.

The shape

add <count> items to <collection> in <model>
  set item.field to value
  set item.field to value
  ...
end

Common use case: kit expansion

When an order contains a kit SKU, expand it into the components and remove the kit:

for order_lines in order
  when order_line.sku is "KIT-STARTER" then
    add 1 * order_line.qty_ordered items to order_lines in order
      set item.sku to "KIT-COMPONENT-A"
      set item.name to "Component A"
      set item.unit_price to 0.0
    end

    add 2 * order_line.qty_ordered items to order_lines in order
      set item.sku to "KIT-COMPONENT-B"
      set item.name to "Component B"
      set item.unit_price to 0.0
    end

    reject order_line  # remove the kit SKU itself
  end
end

For each kit ordered (qty_ordered = 1), add 1 of Component A and 2 of Component B. Then reject the kit line so the warehouse only sees the components.

Common use case: gift wrap

when
  order.notes contains "GIFT"
  or order.custom.is_gift
then
  add 1 item to order_lines in order
    set item.sku to "GIFT-WRAP"
    set item.name to "Gift Wrapping"
    set item.quantity to 1
    set item.unit_price to 0.0
  end
end

Counting

The count is an expression, not just a literal. You can compute it from the order:

accumulate order_lines in order
  line_count: count order_line.id
end

add 1 * line_count items to order_lines in order
  set item.sku to "INSERT"
end

Common patterns:

• 1 item — exactly one.
• N items — a fixed count.
• 1 * order_line.qty_ordered items — one new line per unit of the line that triggered the add.
• <computed_var> items — a count from a session variable or accumulator result.

What item refers to

Inside the add block, item is the new line being created. You can:

• Set fields with set item.field to value.
• Reference the source. When add is inside a for order_lines in order, the surrounding order_line is also accessible — useful for copying fields:

  for order_lines in order
    when order_line.sku is "BUNDLE-A" then
      add 1 item to order_lines in order
        set item.sku to "INCLUDED-A"
        set item.quantity to order_line.qty_ordered  # inherits qty
      end
    end
  end
  

Multiple add blocks

Want to add several different items based on one trigger? Use multiple add blocks:

when order.custom.is_first_purchase then
  add 1 item to order_lines in order
    set item.sku to "WELCOME-PACKET"
  end

  add 1 item to order_lines in order
    set item.sku to "DISCOUNT-COUPON"
  end
end

Each add block adds independently.

Field defaults

If you don’t set a field, it’s blank. Set the fields the warehouse needs — at minimum, the SKU. Other common ones:

Tips

• reject the original. When expanding a kit or replacing a SKU with components, the trigger line usually needs to be rejected in the same iteration so the warehouse doesn’t see both.
• Don’t add inside an accumulate. add modifies the collection mid-iteration; pairing it with an accumulate over the same collection produces inconsistent results.
• Test in the trace harness. Run an order with the trigger condition through the Test tab and confirm the new line appears with all the right fields.