Orderly data, X12, and HTTP credentials in flows
This page covers the steps that read Orderly records, book pickups, send real
X12 to trading partners, and call APIs that need credentials. Every step's full
settings are published in the step catalog (GET /api/v1/flows/catalog).
Get a shipment
orderly.shipment.get loads one shipment by exactly one of shipment_id,
tracking_number, or external_id. When a tracking number or external ID
matches more than one shipment, the newest is used. A shipment that does not
exist fails the step.
{
"key": "shipment",
"type": "orderly.shipment.get",
"config": { "tracking_number": "{{ trigger.payload.tracking }}" }
}
The output holds id, order_id, external_id, tracking_number,
tracking_url, carrier, service, status, status_detail, ship_date,
estimated_delivery, actual_delivery, label_status, tracking_events (each
with timestamp, status, description, and location), and costs
(customer_cost_cents, currency, billing_status). A client's flow can only
load that client's shipments.
Look up inventory
orderly.inventory.lookup reads stock for one sku, at one location_id or
summed across every location.
{
"key": "stock",
"type": "orderly.inventory.lookup",
"config": { "sku": "{{ trigger.payload.sku }}" }
}
The output is sku, on_hand, reserved, available, and locations (one
entry per location with the same three quantities). A SKU with no stock records
returns zeros and an empty list rather than failing.
In a client's flow, the lookup only counts stock synced from that client's own bridges. Stock entered directly in Orderly, or synced from another client's or the organization's bridges, is left out, so a client never sees quantities that are not theirs. A client with no bridge-synced stock for the SKU gets zeros.
Schedule a pickup
orderly.pickup.schedule books a carrier pickup on a
carrier account that supports pickups (today, FedEx).
| Setting | Description |
|---|---|
carrier_account_id | Required. An active account with pickup support |
pickup_date | Required. YYYY-MM-DD |
ready_time, close_time | The window, HH:MM in 24-hour time. Default 09:00 to 17:00 |
location_id | Pick up at one of your locations |
pickup_address | Or an address: address1, city, province, zip, country, and optional address2, company, firstName, lastName, phone |
package_count | 1 to 999, default 1 |
total_weight | Optional { "value", "unit" }, unit oz, lb, g, or kg |
instructions | Optional, up to 500 characters |
With neither location_id nor pickup_address, the pickup is at your default
location. The output is pickup_id, confirmation_number, status,
carrier_account_id, pickup_date, ready_time, close_time,
package_count, and idempotent_replay.
A pickup sends a driver, so this step is handled like a label purchase:
- It cannot skip on error or use an error handler.
- A client's flow can use it: the pickup is booked on your organization's own carrier account for that client, and the client is recorded on the pickup.
- Before calling the carrier, Orderly records a pending pickup keyed to the
run and step. Pending pickups are internal: they never appear under
Pickups or in the pickups API, and cannot be cancelled there. Retrying
the step never books a second pickup; a step that already booked returns the
same pickup with
idempotent_replay: true. - When nothing can have been booked, the pending record is removed and the step
fails for good: the carrier was never reached (missing credentials, a failed
sign-in), or it definitively refused the booking (a
4xxsuch as a bad address). - Any other failure might have come after the carrier booked: a
5xx, a timeout (408), a rate limit (429), or no answer at all. The step fails with Pickup outcome unknown, keeps the pending record, and will not book again, even on retry.
To recover from Pickup outcome unknown, check with the carrier. If the pickup was booked, keep or cancel it with the carrier and resolve the run's exception as ignored. If it was not, resolve the exception as corrected and retry the run. Resolving the exception as corrected or ignored removes the pending record, which lets a retry book again.
Send real X12
exchange.send with "format": "x12" turns its payload into a real X12
interchange, with control numbers from your partner's counters and the
partner's EDI identifiers on the envelope. Three document kinds have
generators:
doc_kind | Transaction set | Payload |
|---|---|---|
shipment | 856 advance ship notice | shipment_id, po_number, items (each sku, quantity), and optional tracking_number, carrier, ship_date, weight_lb |
invoice | 810 invoice | invoice_number, po_number, items (each sku, quantity, price in dollars) |
ack | 855 purchase order acknowledgment | order_number, line_items (each sku, quantity, optional price), optional ordered_at |
{
"key": "asn",
"type": "exchange.send",
"config": {
"partner_id": "{{ params.partner_id }}",
"doc_kind": "shipment",
"doc_type": "856",
"format": "x12",
"payload": {
"shipment_id": "{{ steps.label.output.shipment_id }}",
"po_number": "{{ steps.fetch_order.output.order_number }}",
"tracking_number": "{{ steps.label.output.tracking_number }}",
"carrier": "{{ steps.label.output.carrier }}",
"ship_date": "{{ today() }}",
"items": "{{ steps.lines.output }}"
}
}
}
- X12 for
orderorotherdocuments is refused when you save and publish. doc_typeis set from the transaction set (856,810, or855), and the step output adds it asdoc_type.- A payload missing a required field fails the step and names the field. A partner without EDI identifiers configured fails the step.
- A retried step reuses the document it already generated, so it never takes new control numbers or sends twice.
Every exchange.send needs the partner to have an active outbound connection.
Credentials for HTTP requests
http.request can authenticate to the API it calls with auth. The secrets it
uses are stored on the flow, encrypted, and named in the definition; the
definition never holds a password.
Set a secret on a flow (the value is never returned again):
curl -X PUT https://api.orderly-hub.com/api/v1/flows/$FLOW_ID/secrets/erp_client_secret \
-H "Authorization: Bearer $ORDERLY_API_KEY" \
-H "X-Organization-Id: $ORG_ID" \
-H "Content-Type: application/json" \
-d '{ "value": "s3cr3t" }'
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /api/v1/flows/{id}/secrets | flows:read | List secret names and when they were set |
PUT | /api/v1/flows/{id}/secrets/{name} | flows:write | Create or replace a secret: { "value": "..." } (up to 4,096 characters) |
DELETE | /api/v1/flows/{id}/secrets/{name} | flows:write | Delete a secret |
Names use lowercase letters, digits, and underscores, starting with a letter. A
flow holds up to 50 secrets. Publishing is refused while an auth setting names
a secret the flow does not have, and a secret the published version uses cannot
be deleted (409) until a version without it is published.
When auth is set, url must be a literal https:// URL in the definition,
with no references. Credentials then only ever go to an address you wrote, never
to one chosen by run data.
HTTP Basic sends the username and the secret as an Authorization: Basic
header:
"auth": { "type": "basic", "username": "orderly", "password_ref": "erp_password" }
OAuth 2.0 client credentials fetches a bearer token from token_url and
sends it as Authorization: Bearer:
"auth": {
"type": "oauth2_client_credentials",
"token_url": "https://auth.example.com/oauth/token",
"client_id": "orderly-flows",
"client_secret_ref": "erp_client_secret",
"scopes": ["orders.write"],
"client_auth": "body"
}
- The client ID and secret go in the form body (
client_auth: "body", the default) or as HTTP Basic ("basic"), whichever the provider expects. - Tokens are reused until shortly before they expire (
expires_in, one hour when the provider does not say), so most calls do not fetch a new one. Changing the secret starts a fresh token. - The token request gets the same protections as the main request: HTTPS only, public addresses only, no redirects.
- When the API answers
401, the cached token is dropped and the failure can be retried withon_errorretry, which then fetches a new token. - A rejected token request (a
4xxsuch as bad credentials) fails the step; an outage or rate limit at the token endpoint can be retried.
With auth, Orderly sets the Authorization header itself and ignores one in
headers. Request signing with the flow's signing secret is separate and still
applies unless sign is false.