Group by Step

Group a list of items into buckets based on one or more fields.

What it does

• Takes an input list (array) and groups items into buckets based on one or more keys (for example, customer_id, warehouse, channel).
• Returns a list of groups, where each group contains:
  • The group key (for example, customer_id: 123, warehouse: DE-1).
  • The items in that group (a sub‑array you can loop over with Split or transform further).
• Lets you build aggregation‑style flows (per‑customer, per‑order, per‑warehouse, per‑shipment) without writing code.

When to use it

• When you receive a flat list of items but need to process them per logical bucket:
  • Group order lines by order ID to send each order as a separate payload.
  • Group items by warehouse to create one shipment or reservation per warehouse.
  • Group records by customer, channel, or country for reporting or routing.
• When downstream systems expect one call per group, not per individual item (for example, one API call per order instead of per line).
• When you want to summarize or aggregate data per group in later steps (for example, calculate total quantity per SKU per warehouse).

How to configure

• In the Group by step, select the source array:
  • Incoming payload arrays (for example, data.items, data.lines, data.orders).
  • Arrays from previous steps (for example, steps.outputs.items).
• Define one or more grouping keys:
  • Use references to item fields (for example, item.order_id, item.customer_id, item.warehouse_code, item.marketplace).
  • You can combine multiple fields to create a compound key (for example, order_id + warehouse_code).
• Configure Expected Keys:
  • List the item fields that must be present for grouping to work correctly (for example, item.order_id, item.warehouse_id).
  • Items missing any of the expected keys will follow the behavior defined in the popup:
    • Either be routed to a dedicated “missing keys” group, or
    • Be excluded from the result, or
    • Trigger an earlier validation / Error step (recommended when the key is mandatory for the scenario).
• Review the output shape:
  • The result is an array of groups.
  • Each group contains:
    • key – the grouping values.
    • items – the array of items that belong to this group.

Typical patterns

• Per‑order grouping:
  • Input: list of line items for multiple orders.
  • Group by: order_id.
  • Then: use Split on the output groups to send or sync each order separately.
• Per‑warehouse grouping:
  • Input: inventory changes across multiple warehouses.
  • Group by: warehouse_id.
  • Then: send one payload per warehouse to WMS or ERP.
• Per‑customer or per‑channel grouping:
  • Input: orders or invoices from multiple channels/customers.
  • Group by: customer_id, channel.
  • Then: route groups to different target systems or apply different business rules.

Example configuration (group order lines by order and warehouse)

Scenario goal: from a flat list of order lines, group items by order ID and warehouse so that each group can be processed as a single shipment request.

In the next step, you can connect a Split step to steps.group_by_order_warehouse.outputs.groups and loop over each group (each combination of orderId and warehouse) to create shipments, reservations, or API calls per group.