Overview 

A line item is an individual entry or row in a record or document, such as an order, invoice, purchase order, packing list, or inventory record. Unlike regular fields, which hold just one value, each line item field can have multiple values. In technical terms, they are arrays of objects.

For example:

• The products on an invoice in Zoho Books, each with a name, quantity, rate, and tax.

• The entries on a purchase order, each for a different product from a vendor.

Before line item support, passing this kind of data from one app to another required writing custom formulas to extract individual rows by index, or building custom functions to construct the array from scratch. This made the process fragile and time-consuming.

Why line items are important in workflows? 

The old approach:  without line item support

Without line item support, the only way to pass multi-row data was to extract each row individually, then map each field one by one.

For a WooCommerce order with three products, you would map every field for every row separately:

Item name (1) → Name

Quantity (1) → Quantity

Rate (1) → Price

Item name (2) → Name

Quantity (2) → Quantity

Rate (2) → Price

Item name (3) → Name

Quantity (3) → Quantity

This approach has significant drawbacks:

• The flow only works for a fixed number of rows. If the record has more or fewer items than expected, rows will be missing or the flow will fail.

• Every field needs to be mapped separately for every row, making the setup tedious and error-prone.

• If the trigger's field structure changes, every mapped row breaks and has to be fixed individually.
  
  

• Handling a dynamic number of rows requires a custom function, which needs programming knowledge.
  

The new approach:  with line item support

With line item support, Zoho Flow recognises when a trigger or previous action returns array data and presents it as a mappable line items variable in the action configuration. You configure the fields once, and Zoho Flow will apply the mapping across all rows automatically, regardless of how many rows the trigger or the previous action returns.

 

In the above example discussed, every product in the WooCommerce order appears as a correctly populated row in the Zoho Inventory sales order. No formulas. No custom functions. No hard-coded row count. This works as long as both applications share a compatible field structure, otherwise you could map fields individually.

Note: If an action does not support line items, the line item section will not appear in its configuration panel.

Line items and field groups 

When configuring an action that supports structured data, you may encounter two types of grouped fields: line item and field group. Although they may look similar in the configuration panel, they behave differently.

When to use line item

Map a line item variable to a line item field when you are passing multiple rows of related data where each row has its own set of values. For example:

• Products on an invoice, each with a name, quantity, rate, and tax

• Items on a sales order, each with a SKU, quantity, and discount
  

• Phone numbers on a contact, each with a number, type, and country code
  

When to use field group

Map a field group variable to a field group field when you are passing a single grouped record(one set of values) from one application to another. For example:

• Copying a contact's billing address (street, city, state, zip) from one application to another

• Passing a shipping address from an order to a record in the destination application

The key difference from line items: there are no multiple rows involved. It's a one-to-one transfer of a fixed group of fields. If you're moving a list like multiple products or multiple phone numbers use a line item field instead.

Line items	Field group
Represent multiple records (rows).	Represent a single grouped record.
Support array-based value assignment.	Do not support array-based value assignment.
Each row can receive an array of values (position-based).	Represents a single record. Each field holds one value, and there are no multiple rows.
Example: order items, invoice products, purchase entries.	Example: billing address, shipping address.

Identifying line items in Zoho Flow

In the action configuration panel

Fields that support line items are marked with a line item badge next to the field label. When you click on such a field, you will see a Map as option with two choices: Bulk and Field-by-Field letting you choose how to configure the line item fields.

      

In the Insert variable panel

On the right side of the action configuration, the Insert variable panel lists all available variables from your trigger and previous steps, grouped by step.

Variables that contain line item data are marked with a line item tag, and variables that contain field group data are marked with a field group tag. Click the expand icon next to either to reveal the individual fields within, each shown with its data type, such as string or number. Click any variable to map it to the respective field.

Variables without a tag are standalone single-value variables and can be mapped directly.

Configuring line items 

When you open an action that supports line items, you will see a line item section in the configuration panel. You can configure it in two ways: Bulk and Field-by-Field.

Bulk

Field-by-Field

Bulk

Bulk configuration lets you map the entire line item array from a previous step to the action in one step. Use this when both the applications have a compatible structure and you want to pass all fields without reviewing them individually. Follow the steps below to do the mapping.

1. In the action configuration panel, locate the line item section and click Bulk.

2. In the Insert variable section on the right, select the line item variable from the trigger or previous action's output. Zoho Flow maps the line item variable directly to the line item field.
   
   
   
   

Here, the Phones field is mapped to ${fetchContact_2.Phones} the entire line item variable from the previous step is passed to the field in one go, and all phone rows are transferred automatically.

      

You can also enter values directly as an array. For example, to add multiple phone numbers to the Phones field, enter the values in the format below and each entry will be created as a separate phone record in the Xero contact.
[{"phonenumber":"555 0132","phoneareacode":"415"},{"phonenumber":"555 0198","phoneareacode":"212"},{"phonenumber":"555 0147","phoneareacode":"416"}]

• Phone number (1) → 555 0132

• Phone number (2) → 555 0198

• Phone number (3) → 555 0147

• Phone area code (1) → 415

• Phone area code (2) → 212

• Phone area code (1) → 416
  

where Phone number and Phone area code are the fields within the Phones line item field.

Note: Bulk configuration works only when both applications use the same field structure.

Field-by-Field

Field-by-Field lets you configure each line item field individually. For every field, you can either map a value from a previous step, type a value directly, or if the field offers a dropdown, pick from a list of options.

Regardless of how you assign a value, you also control how it is distributed across rows:

• As an array - Pass a list of values in JSON format. Each value is assigned to the corresponding row by position. Rows with no matching value are marked as null.
  
  
  
  

  Here, the Phone number field is mapped to ${fetchContact_2.Phones.PhoneNumber}, meaning it pulls the phone number directly from the Phones line item variable returned by the previous step, and assigns each number to the corresponding row automatically. 

  Another example, when a trigger returns 4 line items and City is mapped as an array.

  Input: ["New York", "Los Angeles", "Chicago", "Houston"]

   

  Row 1  →  New York

  Row 2  →  Los Angeles

  Row 3  →  Chicago

  Row 4  →  Houston

  Whereas, when you pass a single value as an array with only one entry, it is assigned to the first row only. The remaining rows receive null value.

  Input: ["New York"]

   

  Row 1  →  New York

  Row 2  →  null

  Row 3  →  null

  Row 4  →  null

  • As a single value - Pass one value and it is applied to every row. Use this for fields that are the same across all line items, such as a warehouse location, currency, or country code.
    
    
    
    

      In this example, a single value is passed to the Phone country code field, so the same value is applied to all the rows.

      Input: Phone country code - +1

 

Row 1  →  +1

Row 2  →  +1

Row 3  →  +1

Row 4  →  +1

      For fields with a dropdown, you can either select an existing option which applies the same value to all rows or enter a custom       value. Custom values support array input, so you can assign a different option to each row. 

            

      For example, the phone type differs per item. Select custom value and enter the values in the below format.

      Input: ["Mobile", "Work", "Fax"]

 

            Row 1  →  Mobile

            Row 2  →  Work

            Row 3  →  Fax

            Row 4  →  (empty)

 

Note: Arrays must follow valid JSON format. String values must be enclosed in double quotes, for example, ["Active", "Inactive"] is valid, but [Active, Inactive] is not. Numeric values do not require quotes.

How values are distributed across rows 

The table below shows how a value is assigned to rows, depending on how you enter it.

Assignment mode	Input	Rows	Result
Array input - mapped from previous step	Line items array	Matches source	Each row receives its value by position
Single value - mapped from previous step	Any single field	Any	All rows receive the same mapped value
Typed directly - array	["A", "B", "C"]	5	Row 1=A, Row 2=B, Row 3=C, Rows 4–5=empty
Typed directly - Single value	Active	5	All 5 rows = Active
Selected from a dropdown	Select: Approved	5	All 5 rows = Approved
Custom value - array(line item)	["Approved", "Pending"]	5	Row 1=Approved, Row 2=Pending, Rows 3–5=empty
Custom value - single(field group)	"Approved"	Any	All rows =Approved

Note: When using array input, missing positions are null. Extra values beyond the row count are ignored.

Limitations 

• Not all applications support line items. If the line items section doesn't appear in an action, that app doesn't support it.

• Field groups don't support array input.

• Dropdown fields in field groups only accept a single selected option, custom values with array input aren't supported.
  

Frequently asked questions 

I mapped the trigger's line items array to a field but only the first row appears in the action. What went wrong?

This usually means the field you mapped to is a field group field, not a line item field. Field groups represent a single record and do not support arrays. Make sure you are mapping into the line items section of the action, not into a field group.

Can I apply a different value to each row in a dropdown field?

Yes, but only for line item fields and not field groups. In a line item dropdown field, choose Custom value and enter a JSON array. Each value maps to the corresponding row by position. This is not applicable for dropdown fields in field groups.

Do I need a custom function if both my trigger and action support line items?

In most cases, no. If both applications support line items and the field structures are reasonably compatible, you can map everything directly in the Line items configuration panel. Custom functions are needed only when you need to restructure, filter, or transform the data for example, to exclude certain rows, calculate a derived value, or reformat a field.

What happens if the trigger returns no line items?

If the trigger returns an empty line items array, no rows will be created in the action. The flow will still complete successfully, but the record in the destination app will have no line item entries. To handle this, add a condition step before the action to check that the line items array is not empty before the flow proceeds.

What happens when fields in a Field-by-Field configuration have arrays of different lengths?

What happens if I include a null value inside an array?