Skip to main content

The reference language

Flow steps pass data to each other with references: small expressions inside {{ }} that Orderly fills in just before a step runs. Any string in a step's configuration can hold one:

{
"key": "notify",
"type": "http.request",
"config": {
"url": "https://ops.example.com/orders",
"body": {
"order": "{{ steps.fetch_order.output.order_number }}",
"state": "{{ upper(trigger.payload.ship_to.state) }}"
}
}
}

A reference is either a path into the run's data or a call to one of 58 helper functions. Nothing inside {{ }} is ever evaluated as code.

The roots​

Every path starts at one of six roots, plus four that exist only in specific places.

RootWhat it holds
triggerWhat started the run: trigger.payload (the payload) and trigger.meta (where it came from)
stepsThe results of earlier steps: steps.<key>.output
orgYour organization: org.id and org.name
inputsThe trigger payload again, checked against the definition's inputs schema when it has one
paramsThe parameters a template install provided; an empty object otherwise
runThe current run: run.id
errorOnly in error handler steps: the failed step's error.step (key), error.type, and error.message
item, indexOnly in a collection.map expression, or in a step inside a For each loop: the current item and its 0-based position
loopOnly in a step inside a For each loop: loop.item, loop.index, loop.count, loop.first, and loop.last

trigger.payload and trigger.meta​

trigger.payload is the data the trigger delivered: the JSON body of a webhook or endpoint request, the query string of a GET endpoint request, or the payload of a manual run. Bridge order events deliver order_id, external_id, and the normalized order; a new shipment delivers shipment. Exchange document events deliver the document_id and what the document produced. trigger.meta says where the run came from:

Triggertrigger.meta fields
Webhooksource, headers (user-agent and x-request-id)
Schedulesource, fire_key
Bridge eventsource, event, bridge_id, record_id
Exchange documentsource, partner_id, document_id, doc_type
Endpointsource, endpoint_id, endpoint_slug, contract, request_id, caller, key_id
Manualsource, plus any meta the caller passed

A replayed run keeps the original meta and adds replay_of, the ID of the run it replays. Runs of a client's flow also carry end_user_id.

inputs​

If the flow definition has an inputs JSON Schema, every new run's payload is validated against it before the run starts, and a payload that does not match is refused. inputs and trigger.payload hold the same data; use inputs to make it clear a step relies on the validated shape.

steps​

steps.<key>.output is what a step stored when it succeeded. A step can only reference steps that run before it, and a step that was skipped, or sits in a branch lane that was not chosen, has no output. The output shape of each step type is published in the step catalog (GET /api/v1/flows/catalog, field output_schema). The most common ones:

Stepoutput
orderly.order.getThe full order record, such as id, external_id, order_number, status, shipping_address, line_items, totals
orderly.order.ingestorder_id, external_id, action (created or updated)
orderly.ratequotes (each with carrier, service, amount_cents, currency, transit_days), best, strategy, mode
orderly.label.purchaseshipment_id, tracking_number, carrier, service, label_url, customer_cost_cents, currency
http.requeststatus and body (parsed JSON, or the raw text)
branchchosen (the lane key, or null) and next_keys
loop.for_eachtotal, count, succeeded, failed, not_run, halted, and items (one result per item, with the outputs of its kept steps). See For each loops
wait.eventThe payload of the signal that resumed the run
transform.jsWhatever the script returns
transform.parseThe parsed document: for CSV, a list of objects keyed by header
transform.serializeThe rendered document text
collection.map, collection.filter, collection.sort, collection.dedupeThe resulting list
collection.aggregateOne object of named results, or a list of { key, ... } per group
orderly.shipment.getid, status, carrier, service, tracking_number, tracking_events, and costs (customer_cost_cents, currency, billing_status)
orderly.inventory.lookupsku, on_hand, reserved, available, and locations
orderly.pickup.schedulepickup_id, confirmation_number, status, pickup_date

run​

run.id is the ID of the run that is executing, available from the first step. Hand it to another system so it can signal the run later. In a dry run it is the placeholder dry-run.

Path syntax​

  • Separate segments with dots: trigger.payload.ship_to.city.
  • Index into a list with [n] after a segment, or with a numeric segment: trigger.payload.items[0].sku and trigger.payload.items.0.sku read the same value.
  • Segments use letters, digits, and underscores. A key with other characters (such as a hyphen or a space) cannot be referenced.
  • Spaces just inside the braces are ignored: {{ org.id }} and {{org.id}} are the same.

Whole values and text​

How a reference resolves depends on where it sits:

  • A string that is exactly one reference takes the value with its type. If trigger.payload.parcels is a list, "{{ trigger.payload.parcels }}" resolves to that list, not to text. A path that does not exist resolves to nothing, so an optional setting is simply left out.
  • A reference inside other text is rendered as text. Missing and null values render as an empty string, and objects and lists render as JSON: "Order {{ trigger.payload.number }} shipped" becomes "Order 1001 shipped".

Functions​

Helpers transform a value inside the braces, for example {{ upper(trigger.payload.state) }}. Arguments can be reference paths, single-quoted text such as 'Guest' (escape a quote with a backslash), numbers, true, false, null, or nested helper calls. A call to a name that is not a helper stays as literal text (and is flagged when you save), but a call to a helper is always evaluated, including text saved before that helper existed. An expression can be up to 400 characters, with at most 10 arguments per call and helpers nested at most 3 levels deep.

Every helper is total: when it cannot work with its input (text where it needs a number, an impossible date, division by zero) it returns a missing value instead of failing the step. A missing value behaves like a path that does not exist: a whole-string reference leaves an optional setting out, embedded text renders it as empty, and default or coalesce can replace it. Numbers may be numbers or numeric text such as "12.50".

Text​

SignatureReturnsExample
upper(s)The text in upper case.{{ upper(trigger.payload.ship_to.state) }} turns nj into NJ
lower(s)The text in lower case.{{ lower(trigger.payload.email) }}
trim(s)The text without leading or trailing whitespace.{{ trim(trigger.payload.po_number) }}
title_case(s)Each word with its first letter upper case and the rest lower case.{{ title_case('ada LOVELACE') }} gives Ada Lovelace
concat(...parts)The parts joined into one text, with null and missing parts left out.{{ concat(trigger.payload.first_name, ' ', trigger.payload.last_name) }}
join(list, separator?)The list items joined into one text with the separator (, by default).{{ join(trigger.payload.tags, ' / ') }}
substring(s, start, end?)The characters from start (0-based) up to, not including, end. Negative positions count from the end.{{ substring(trigger.payload.zip, 0, 5) }}
replace(s, find, replacement)The text with every occurrence of find replaced. find is plain text, never a pattern.{{ replace(trigger.payload.phone, '-', '') }}
split(s, separator)The text cut into a list at each separator.{{ split(trigger.payload.skus, ',') }}
length(v)The number of characters in a text, or items in a list.{{ length(trigger.payload.note) }}
pad_start(s, length, fill?)The text padded at the start to length (at most 1000) with fill (a space by default).{{ pad_start(trigger.payload.store, 5, '0') }} turns 42 into 00042
pad_end(s, length, fill?)The text padded at the end.{{ pad_end(trigger.payload.code, 10) }}
starts_with(s, prefix)true when the text starts with the prefix (case-sensitive).{{ starts_with(trigger.payload.sku, 'KIT-') }}
ends_with(s, suffix)true when the text ends with the suffix (case-sensitive).{{ ends_with(trigger.payload.email, '@acme.com') }}
contains(s, part)true when the text contains part, or when a list holds an item equal to it.{{ contains(trigger.payload.tags, 'fragile') }}

upper, lower, trim, title_case, substring, and replace pass a null or missing value through unchanged, so you can wrap them in default: {{ default(upper(trigger.payload.country), 'US') }}.

Math​

SignatureReturnsExample
number(v)The value as a number; missing when it is not a finite decimal number.{{ number(trigger.payload.weight_lb) }} turns "12.5" into 12.5
round(n, digits?)The number rounded to 0 to 10 decimal places (0 by default).{{ round(trigger.payload.weight_lb, 1) }}
add(a, b)a plus b.{{ add(trigger.payload.subtotal, trigger.payload.tax) }}
subtract(a, b)a minus b.{{ subtract(trigger.payload.ordered, trigger.payload.shipped) }}
multiply(a, b)a times b.{{ multiply(trigger.payload.price, trigger.payload.qty) }}
divide(a, b)a divided by b; missing when b is zero.{{ divide(trigger.payload.weight_oz, 16) }}
mod(a, b)The remainder of a divided by b, with the sign of a; missing when b is zero.{{ mod(trigger.payload.line, 2) }}
abs(n)The number without its sign.{{ abs(trigger.payload.adjustment) }}
floor(n)The largest whole number at or below n.{{ floor(trigger.payload.weight_lb) }}
ceil(n)The smallest whole number at or above n.{{ ceil(trigger.payload.weight_lb) }}
min(...numbers)The smallest number, or the smallest item when given one list. Values that are not numbers are ignored.{{ min(trigger.payload.quotes) }}
max(...numbers)The largest number, or the largest item of one list.{{ max(trigger.payload.length, trigger.payload.width) }}
sum(list)The total of the numeric items (0 for an empty list).{{ sum(pluck(trigger.payload.lines, 'qty')) }}
avg(list)The average of the numeric items; missing when there are none.{{ avg(pluck(trigger.payload.lines, 'price')) }}

Results are cleaned of binary rounding noise, so {{ add(0.1, 0.2) }} is 0.3. For money, prefer whole minor units such as cents.

Dates​

Dates are read as ISO 8601 text (2026-10-15, 2026-10-15T08:30:00Z, or with an offset such as -05:00; text without a zone is UTC) or as milliseconds since 1970. Helpers that return a moment return ISO 8601 UTC text such as 2026-10-15T13:45:30.000Z. Everything works in UTC and never depends on a locale. An impossible date such as 2026-02-30 is missing, never an error.

SignatureReturnsExample
now()The current time. It is fixed for the whole step, so every use agrees.{{ now() }}
today()Today's UTC date as YYYY-MM-DD.{{ today() }}
timestamp(date?)Milliseconds since 1970 for the date, or for now.{{ timestamp(trigger.payload.created_at) }}
format_date(date, mask)The date written with a mask.{{ format_date(trigger.payload.shipped_at, 'MM/DD/YYYY') }}
parse_date(text, mask)Text written with a mask, read into an ISO timestamp.{{ parse_date(trigger.payload.ship_date, 'YYYYMMDD') }}
date_add(date, amount, unit)The date moved by a whole amount of years, months, weeks, days, hours, minutes, or seconds (singular works too). Negative amounts move back.{{ date_add(now(), 2, 'days') }}
date_diff(from, to, unit)The whole number of units from one date to the other, negative when to is earlier. Only complete units count.{{ date_diff(trigger.payload.ordered_at, now(), 'days') }}

A mask is text built from the tokens YYYY (year), MM (month), DD (day), HH (hour, 00 to 23), mm (minute), and ss (second), each at most once. Digits, punctuation, spaces, and the letters T and Z are copied as is, so 'DD.MM.YYYY', 'YYYYMMDDHHmmss', and 'YYYY-MM-DDTHH:mm:ssZ' all work. Any other letters must be in brackets, as in '[Week of] DD/MM', so a mistyped token such as dd or YY makes the mask invalid (the helper returns nothing) instead of printing letters. MM is always the month: a mask with MM needs YYYY or DD too, which catches HH:MM written for HH:mm. parse_date needs YYYY, MM, and DD, and the text must match the mask exactly, including two digits for each two-letter token. Mappings use the same masks.

Adding months keeps the day of the month, or uses the last day of a shorter month: date_add('2026-01-31', 1, 'months') is February 28. date_diff counts months the same way, so January 31 to February 28 is one month.

Logic​

SignatureReturnsExample
if(condition, then, else?)then when the condition is truthy, otherwise else (missing when omitted).{{ if(trigger.payload.rush, 'PRIORITY', 'GROUND') }}
eq(a, b)true when the values are the same. Lists and objects compare by content. Text and numbers never equal each other, so use number() first.{{ eq(trigger.payload.country, 'US') }}
neq(a, b)true when eq is false.{{ neq(trigger.payload.status, 'cancelled') }}
gt(a, b), gte, lt, lteComparisons. Numbers and numeric text compare as numbers, other text character by character (so ISO dates compare correctly); anything else is false.{{ gt(trigger.payload.total, 100) }}
not(v)true when the value is falsy.{{ not(trigger.payload.gift) }}
and(...values)true when every value is truthy.{{ and(trigger.payload.paid, trigger.payload.address) }}
or(...values)true when any value is truthy.{{ or(trigger.payload.rush, trigger.payload.vip) }}
coalesce(...values)The first value that is neither missing nor null.{{ coalesce(trigger.payload.ship_to.phone, trigger.payload.phone, 'n/a') }}
default(value, fallback)The value, or the fallback when it is null, missing, or empty text.{{ default(trigger.payload.ship_to.name, 'Customer') }}

Truthiness: missing, null, false, 0, empty text, and an empty list are falsy. Everything else is truthy, including the text "false" and "0". coalesce treats empty text as a value; default does not.

Lists​

SignatureReturnsExample
first(list)The first item; missing for an empty list.{{ first(pluck(trigger.payload.lines, 'sku')) }}
last(list)The last item.{{ last(trigger.payload.events) }}
count(list)The number of items; missing when the value is not a list.{{ count(trigger.payload.lines) }}
pluck(list, 'path')The value at path in each item, with missing values left out.{{ pluck(trigger.payload.lines, 'sku') }}
unique(list)The list without repeats, keeping the first of each.{{ unique(pluck(trigger.payload.lines, 'warehouse')) }}
includes(list, value)true when the list holds an item equal to the value.{{ includes(trigger.payload.tags, 'b2b') }}

A call result cannot be followed by a path, so {{ first(list).sku }} is invalid. Reach into items with pluck, or use a collection step.

Formatting​

SignatureReturnsExample
format_number(n, decimals, grouping?)The number as text with exactly decimals places (0 to 10) and a . decimal point, with grouping between thousands when given. Missing beyond 9,007,199,254,740,991, where numbers stop being exact.{{ format_number(trigger.payload.total, 2, ',') }} gives 1,234.50
currency(minor_units, code)An amount in whole minor units with its ISO 4217 code, using the currency's own decimal places (0 for JPY, 3 for KWD). Missing beyond the same limit.{{ currency(steps.label.output.customer_cost_cents, 'USD') }} gives 12.34 USD

Organization data​

SignatureReturnsExample
lookup('table', key, default?)The value stored under key in one of your lookup tables, or default (missing when omitted) when the key is absent.{{ lookup('carrier_scac', trigger.payload.carrier, 'UNKN') }}
in_set(value, 'set name')true when the value, as text, is in the named condition set, false otherwise.{{ if(in_set(trigger.payload.zip, 'Remote ZIPs'), 'GROUND', 'EXPRESS') }}

The table slug and the set name must be quoted text, so publishing can check that they exist. Before a step runs, Orderly loads every key the step asks for in one query per table, so a step that looks up many keys stays fast.

Guards with when​

A step can carry a when guard so it only runs when its conditions match; otherwise the step is skipped and the run continues. A guard is a list of conditions and a match_mode of all (the default) or any:

{
"key": "buy_label",
"type": "orderly.label.purchase",
"config": { "order_id": "{{ trigger.payload.order_id }}" },
"when": {
"match_mode": "all",
"conditions": [
{ "field": "steps.fetch_order.output.status", "operator": "equals", "value": "pending" },
{ "field": "trigger.payload.total", "operator": "greater_than", "value": 0 }
]
}
}

In a condition, field is a plain path without braces, read from trigger, steps, inputs, or params, and inside a For each loop also from item, index, and loop. value is a literal. The operators are equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, greater_than_or_equals, less_than, less_than_or_equals, in, not_in, exists, not_exists, and regex, plus in_set and not_in_set, which take a setId pointing at a condition set instead of a value. Text comparisons ignore case, and the greater_than and less_than families only match numbers. Branch lanes use the same condition format.

What is checked when​

When you save a draft or publish, Orderly checks every reference without running anything:

  • Each {{ }} block parses: known function names, the right number of arguments, closed quotes, quoted table and set names, and the length and nesting limits.
  • Each path starts with one of the roots, and error, item, index, and loop are only used where they exist.
  • Each steps.<key> names a step that exists and runs earlier.

A draft saves even with problems so you can keep working, but a flow with any of these problems cannot be published. Publishing also checks that every lookup table and condition set the flow names exists in your organization.

When a step runs, its references are resolved against the run's live data, then the resolved configuration is validated against the step's settings. A field that expects an ID must resolve to a real ID, and a list must resolve to a list; text from your data that merely looks like {{ ... }} is never resolved a second time. If the resolved configuration is invalid, the step fails with a message naming the field, and retrying will not help until the data or the flow changes.

Check references with a dry run

A dry run shows each step's resolved input, so you can see exactly what every reference turned into for a sample payload before you publish.