Skip to main content

Build a flow

A flow is an automation you draw instead of code. It starts from a trigger (a webhook, a schedule, a bridge event, a partner document, an HTTP endpoint, or a manual run) and then runs a list of steps in order: look up an order, transform a payload, call a bridge task, rate shop, buy a label, send a partner document, call an outside API, wait for an event, and more. Each step can read the trigger payload and the output of any earlier step through references, so data flows from one step to the next without glue code.

Open Flows

The Flows section has tabs for Flows, Runs, Exceptions, and Endpoints. Partners who manage clients through the embed also see Templates and Clients (see Flows for your clients).

Permissions

Viewing flows needs the flows.read permission. Editing, testing, and publishing need flows.write. Starting, cancelling, replaying, and signaling runs need flows.run. Acting on exceptions needs flows.triage. Flows is a plan feature: if your plan does not include it, API keys get 402 on the Flows API.

Create a flow​

On the Flows tab, click Create flow. Give it a Name and pick a Trigger:

TriggerStarts a run whenYou also set
WebhookSomething POSTs JSON to the flow's private intake URLNothing
ScheduleThe cron expression firesCron (five fields, for example */15 * * * *) and Timezone
Bridge eventA bridge reports a new or updated order, or a new shipmentThe Bridge and which Events to listen for
Exchange documentA trading partner document arrivesThe Trading partner
EndpointA caller hits the flow's virtual endpointThe endpoint, created after the flow
ManualSomeone clicks Run now, or calls the APINothing

If you manage clients through the embed, you can also pick a Client so the flow runs on that client's behalf.

When the flow is created, Orderly shows Save your flow secrets once. The HTTP signing secret signs every HTTP request step the flow sends, so the receiving system can verify it came from you. Copy it now; it cannot be shown again, only rotated.

Webhook flows show their Intake URL at the top of the flow page, with a copy button. Treat it like a password. If it may have been seen by someone who should not have it, rotate it with Rotate next to the URL (members who can edit flows) or through the Flows API. Rotating changes the intake URL: the old one stops working at once, so update every system that sends to it. To also require a signature on every intake call, turn on verify_hmac in the flow's trigger configuration through the Flows API; the response carries a Webhook secret, shown once.

The designer​

Opening a flow takes you to the designer. The toolbar along the top shows a problems chip (No problems, or a count you can hover to read), an Unsaved changes badge while you have edits, and the actions: Undo, Redo, the definition file menu (Export definition and Import definition), History, Test, Save draft, and Publish.

Below the toolbar are two tabs, Canvas and JSON. Selecting a step opens the property panel on the right.

The canvas​

The canvas draws your flow from top to bottom: the Trigger node first, then each step in the order it runs. To add steps:

  • Click Add step (top right of the canvas) to append a step at the end.
  • Hover a step and click the + under it to add a step right after it.
  • Click the small + on a connection to insert a step between two others.

Each of these opens the step palette. To reorder, drag a step and drop it onto a connection. Tidy layout straightens the nodes back into a clean column. A Branch step fans out into lanes, and each lane holds its own steps. A For each step draws a frame around the steps it runs for each item; add steps inside the frame to run them per item.

The step palette​

The palette is a searchable list of every step you can add, grouped as Orderly, Connectors, Transform, and Control. Each entry shows a one-line description of what it does, and a dollar sign marks a step that moves money.

StepWhat it does
Get orderLoads one order by order_id or external_id and stores the full order record. Client flows can only load their own client's orders.
Ingest orderCreates or updates an order as if it arrived through the given bridge, with the same validation as bridge ingestion.
Create shipmentRecords a shipment, for example a tracking number from an outside carrier. Retries reuse the same idempotency key, so a run creates the shipment once.
Rate shopQuotes carrier rates for a saved operation or for a shipment described inline, ordered by strategy (cheapest, fastest, or best-value).
Purchase labelBuys a label for the order's assigned carrier service, charging your balance. Funds are held before the carrier is called, and this step can never be set to skip on error.
Get shipmentLoads one shipment by ID, tracking number, or external ID with its status, carrier, service, tracking events, and costs.
Look up inventoryReads on-hand, reserved, and available quantities for a SKU at one location or across all of them.
Schedule pickupBooks a carrier pickup on an account with pickup support. The booking is recorded before the carrier is called, so a retry never books twice, and this step can never be set to skip on error.
Create claimOpens a draft carrier claim for a shipment with a reason. If an open claim with the same reason already exists, that claim is returned instead.
Bridge taskRuns a named task on one of your bridges and stores the task's result.
Send exchange documentCreates an outbound document for a trading partner and transmits it over the partner's active connection. With the x12 format it generates a real X12 856, 810, or 855. A retried step does not resend a document that was already sent.
HTTP requestSends a JSON request to a public HTTPS URL and stores the response status and body. Requests are signed with the flow's signing secret unless you turn signing off, and can carry HTTP Basic or OAuth 2.0 credentials stored as flow secrets.
JavaScript transformRuns your code in a sandbox with a one-second limit and stores what it returns.
Declarative mappingApplies a saved exchange mapping, or one written into the step, to render or parse a document.
Parse documentReads CSV, XML, or JSON text into data without a mapping.
Serialize documentWrites data out as CSV, XML, or JSON text without a mapping.
Map list, Filter list, Aggregate list, Sort list, Remove duplicatesWork on a list of up to 1,000 items in one step. See Transform data in flows.
BranchRuns the steps of the first lane whose conditions match. A lane with no conditions always matches.
For eachRuns the steps inside it once for each item of a list, up to 100 items by default and 1,000 at most. A loop that buys labels, books pickups, or voids labels needs Max items and an overflow choice set. See For each loops.
Wait for eventPauses the run until a named event is signaled or a timeout passes. See Waits and signals.
RespondSets the HTTP response for an endpoint-triggered run. Only offered in flows that use the endpoint trigger.

The property panel​

Select a step to edit it. The panel shows the step's description (and a Docs link when the step has one), then:

  • Step key: the step's name in references, such as fetch_order. Keys start with a lowercase letter and use lowercase letters, digits, and underscores, up to 64 characters. Renaming a key does not rewrite references to it; after saving, the problems chip flags any reference left pointing at the old key.
  • Configuration: a form generated from the step's settings. Fields that pick a bridge, mapping, or trading partner offer a picker by name, with a switch to type an expression instead. Rate shop has its own form: rate from Shipment details (ship to, an optional ship from, and parcels) or From operation reference.
  • Run only when: optional guard conditions. Click Add guard to add one; the step is skipped when the guard does not match.
  • On error: Fail the run (the default), Skip and continue, or Retry with Max attempts (1 to 10) and a Backoff such as 5s, 2m, or 1h. Money steps cannot skip on error. A step can also run a lane of handler steps when it fails; see Handle step errors.
  • Delete step, with a confirmation.

References and autocomplete​

Any text field can hold a reference such as {{ trigger.payload.order_id }} or {{ steps.fetch_order.output.order_number }}. Type {{ and the designer suggests what you can reference from that step: the reference roots, the helper functions, the keys of the trigger payload, and the outputs of earlier steps. Payload keys come from the endpoint's request schema, the payload you last captured or tested with, or the latest run. Fields also have an Insert reference button that lists every reference available.

The full syntax is in The reference language.

The JSON tab​

The JSON tab shows the whole flow definition as JSON, with any problems listed under it. Edit it directly, then click Apply to load your edits into the designer, or Revert to discard them. You cannot save while JSON edits are unapplied.

Export definition downloads the definition as a file, and Import definition loads one (up to 1 MB) for you to review and save.

Undo and redo​

Use the Undo and Redo buttons, or press Cmd+Z (Ctrl+Z) to undo and Cmd+Shift+Z (Ctrl+Shift+Z or Ctrl+Y) to redo. Text fields keep their own undo while you type in them.

Drafts and publishing​

Your edits live in a draft. Click Save draft to store it. A draft saves even when it has problems, so you can save work in progress; the problems chip lists everything that still needs fixing.

A flow only runs its published version. Publish is available once the draft is saved, has no unsaved edits, and has no known problems. It opens a Publish changes dialog that compares the draft with the currently published version and lists each step key as Added, Removed, or Changed. For scheduled and endpoint flows, the dialog also reminds you that publishing changes what the live schedule or endpoint runs.

Publishing checks the draft one more time and refuses it when, for example:

  • A step references a step that runs later, or one that does not exist.
  • A money step is set to skip on error or given an error handler.
  • A lookup table or condition set the flow names does not exist.
  • An HTTP request uses a credential secret that is not set on the flow, or sends credentials to a URL that is not a literal https:// address.
  • The flow uses a Respond step without the endpoint trigger.
  • An endpoint flow does not have its endpoint yet.
  • A client's flow uses a bridge that belongs to a different client.

Runs already in progress finish on the version they started with. New runs use the newly published version.

Someone else saved first?

If another session saved or published the flow after you opened it, saving shows This draft changed elsewhere. Choose Reload draft to take the newer version and drop your edits, Overwrite to save yours over it, or Keep editing.

Test with a dry run​

A dry run walks the flow against a sample payload without changing anything.

  • Click Test to dry-run what is in the designer right now, unsaved edits included, with an empty payload. The canvas is painted with each step's result.
  • Click the arrow next to Test (Test with a payload) to open the test drawer. Paste a Test payload, or capture one with Use recent run, Use latest run payload, or, for endpoint flows, Use a recent request. Then click Run test.

Each step reports a status with its Resolved input and Output:

StatusMeaning
executedThe step ran for real: transforms, mappings, Get order, Branch, and Respond
resolvedThe step's references were resolved and checked, but it was not called
skippedA guard did not match, the step sits in a lane that was not chosen, or it is a Wait for event step
errorThe step's configuration did not resolve or the step failed

Steps that write data or call outside systems never run in a dry run: Bridge task, Send exchange document, HTTP request, Ingest order, Create shipment, Rate shop, Purchase label, and Create claim only resolve their configuration. Nothing is written and no money moves. Because those steps produce no output in a dry run, later steps that read their output resolve to empty values.

The payload you capture or test with also teaches autocomplete the keys of your trigger payload.

Versions and restore​

Click History to open Version history. It lists every version with its number, status (draft, published, or archived), and when it was published. Select one to preview it read-only in the designer. Restore as draft copies that version into your draft, ready to review and publish again.

Run, pause, and archive​

The flow page header has the flow's actions:

  • Run now starts a run of the published version. It appears on active flows with the manual trigger.
  • Duplicate creates a copy of the flow with the designer's current definition, unsaved edits included. The copy gets its own secrets, shown once.
  • Pause stops triggers from starting new runs; Resume turns them back on.
  • Archive stops the flow for good. An archived flow is read-only and cannot be unarchived.

Under the designer, Recent runs lists the flow's last ten runs. Click one to open it.

Next steps​