Skip to main content

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).

SettingDescription
carrier_account_idRequired. An active account with pickup support
pickup_dateRequired. YYYY-MM-DD
ready_time, close_timeThe window, HH:MM in 24-hour time. Default 09:00 to 17:00
location_idPick up at one of your locations
pickup_addressOr an address: address1, city, province, zip, country, and optional address2, company, firstName, lastName, phone
package_count1 to 999, default 1
total_weightOptional { "value", "unit" }, unit oz, lb, g, or kg
instructionsOptional, 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 4xx such 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_kindTransaction setPayload
shipment856 advance ship noticeshipment_id, po_number, items (each sku, quantity), and optional tracking_number, carrier, ship_date, weight_lb
invoice810 invoiceinvoice_number, po_number, items (each sku, quantity, price in dollars)
ack855 purchase order acknowledgmentorder_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 order or other documents is refused when you save and publish.
  • doc_type is set from the transaction set (856, 810, or 855), and the step output adds it as doc_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" }'
MethodPathScopeDescription
GET/api/v1/flows/{id}/secretsflows:readList secret names and when they were set
PUT/api/v1/flows/{id}/secrets/{name}flows:writeCreate or replace a secret: { "value": "..." } (up to 4,096 characters)
DELETE/api/v1/flows/{id}/secrets/{name}flows:writeDelete 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 with on_error retry, which then fetches a new token.
  • A rejected token request (a 4xx such 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.