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.
| Root | What it holds |
|---|---|
trigger | What started the run: trigger.payload (the payload) and trigger.meta (where it came from) |
steps | The results of earlier steps: steps.<key>.output |
org | Your organization: org.id and org.name |
inputs | The trigger payload again, checked against the definition's inputs schema when it has one |
params | The parameters a template install provided; an empty object otherwise |
run | The current run: run.id |
error | Only in error handler steps: the failed step's error.step (key), error.type, and error.message |
item, index | Only in a collection.map expression, or in a step inside a For each loop: the current item and its 0-based position |
loop | Only 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:
| Trigger | trigger.meta fields |
|---|---|
| Webhook | source, headers (user-agent and x-request-id) |
| Schedule | source, fire_key |
| Bridge event | source, event, bridge_id, record_id |
| Exchange document | source, partner_id, document_id, doc_type |
| Endpoint | source, endpoint_id, endpoint_slug, contract, request_id, caller, key_id |
| Manual | source, 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:
| Step | output |
|---|---|
orderly.order.get | The full order record, such as id, external_id, order_number, status, shipping_address, line_items, totals |
orderly.order.ingest | order_id, external_id, action (created or updated) |
orderly.rate | quotes (each with carrier, service, amount_cents, currency, transit_days), best, strategy, mode |
orderly.label.purchase | shipment_id, tracking_number, carrier, service, label_url, customer_cost_cents, currency |
http.request | status and body (parsed JSON, or the raw text) |
branch | chosen (the lane key, or null) and next_keys |
loop.for_each | total, count, succeeded, failed, not_run, halted, and items (one result per item, with the outputs of its kept steps). See For each loops |
wait.event | The payload of the signal that resumed the run |
transform.js | Whatever the script returns |
transform.parse | The parsed document: for CSV, a list of objects keyed by header |
transform.serialize | The rendered document text |
collection.map, collection.filter, collection.sort, collection.dedupe | The resulting list |
collection.aggregate | One object of named results, or a list of { key, ... } per group |
orderly.shipment.get | id, status, carrier, service, tracking_number, tracking_events, and costs (customer_cost_cents, currency, billing_status) |
orderly.inventory.lookup | sku, on_hand, reserved, available, and locations |
orderly.pickup.schedule | pickup_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].skuandtrigger.payload.items.0.skuread 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.parcelsis 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
nullvalues 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
| Signature | Returns | Example |
|---|---|---|
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
| Signature | Returns | Example |
|---|---|---|
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.
| Signature | Returns | Example |
|---|---|---|
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
| Signature | Returns | Example |
|---|---|---|
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, lte | Comparisons. 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
| Signature | Returns | Example |
|---|---|---|
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
| Signature | Returns | Example |
|---|---|---|
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
| Signature | Returns | Example |
|---|---|---|
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, andloopare 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.
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.