Headless & Integration package

Order orchestration API

A synchronous order endpoint for your storefront: validate, price, fraud-screen, reserve stock, authorise payment and create the shipment in one call.

Headless / APIAdvanced~25 min setupv1.0.0
Download .utpkg 20 KBHow to install

About this package

What it does

Order orchestration API turns one storefront call into a complete, ordered set of back-office steps. The storefront posts the order (order id, customer, email, lines with sku, quantity and price, the shipping address and a payment token reference from your payment provider) and waits for the answer: the workflow runs as middleware and its response is the result.

The workflow rejects incomplete orders straight away, then totals the lines and adds shipping and tax. The Fraud screening decision table looks at the order value, shipping country, whether the customer is new and whether billing and shipping countries differ, and returns accept, review or reject with a risk score. Accepted orders reserve stock in the inventory API, authorise the payment and create the shipment in the fulfilment API. If the payment is declined the reservation is released.

Orders flagged for review are still accepted, but the shipment is created on hold and a Manual fraud review runs in the background: a reviewer releases the shipment or cancels the order, voiding the authorisation and releasing the stock. The caller always gets result, order_status, reason, reservation_id, authorization_id, shipment_id and estimated_delivery. Card data never passes through the workflow.

Headless / API

Called synchronously: the caller waits and receives the workflow's final variables as the response.

Another system starts it over REST or an inbound webhook. No UI is needed; people only appear where a decision needs a human.

The flow

Step by step

  1. 1

    Order posted

    The storefront posts the order, customer, lines, shipping address and a payment token reference, and waits for the response.

  2. 2

    Validate and price

    Missing ids, token or lines are rejected with a 400. Line totals, shipping and tax give the order total.

  3. 3

    Screen for fraud

    The Fraud screening decision table returns accept, review or reject and a risk score; rejected orders get a 422.

  4. 4

    Reserve and authorise

    Stock is reserved and the payment authorised. A declined payment releases the reservation and returns a 402.

  5. 5

    Create the shipment

    The shipment is created, on hold if the order needs review, and the caller gets the ids and estimated delivery.

  6. 6

    Review in the background

    Flagged orders start Manual fraud review: a reviewer releases the shipment or cancels, voiding the payment and stock.

Order orchestration — Synchronous order API for a storefront: validates the order, prices it, screens it for fraud, reserves stock, authorises payment and creates the shipment, then answers the caller with the ids and delivery estimate. The same canvas you get in the designer after installing.

Sub-workflow: Manual fraud review

Runs in the background for orders the fraud rules flag for review: a reviewer releases the held shipment or cancels the order (voiding the payment authorisation and the shipment).

Forms

Inputs and task forms

The inputs a caller passes when it starts a run, and the forms people complete when the process needs a decision.

Start inputs

Order orchestration

Passed by the calling system

Order id * order_id · textStorefront order id
Customer id * customer_id · textCustomer id in the storefront
Email email · emailname@company.comCustomer email
Lines * lines · json{ … }Order lines: [{ sku, qty, price }] with unit prices excluding tax
Currency currency · textISO currency code
Shipping address * shipping_address · json{ … }Shipping address { name, line1, city, postcode, country }
Billing country billing_country · textCountry of the payment method / billing address (ISO code)
New customer new_customer · booleanTrue when this is the customer's first order
Payment token * payment_method_ref · textPayment-method token from your payment provider (a reference, never card data)
Shipping service shipping_service · textShipping service code
Tax rate tax_rate · number0Sales tax rate applied to the subtotal (0.15 = 15%)
Free shipping threshold free_shipping_over · number0Subtotal from which shipping is free
Shipping fee shipping_fee · number0Flat shipping fee below the threshold

User Task · Manual fraud review

Review order

Fraud review: order {{order_id}} · {{currency}} {{order_total}} · score {{risk_score}}

Checks done * checks · choice
Phone verifiedEmail verifiedOrder history OKNo checks possible
Reviewer note * note · text
Release orderCancel order

Headless

Call it from your systems

Every workflow can be started over REST, MCP or the CLI, whatever its trigger, with the sample input below. Runs start straight away on the published version; replace <workflow id> with the id the install created.

REST

shell
curl -X POST "$USERTASKS_URL/api/v1/workflows/start" \
  -H "Authorization: Bearer $USERTASKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"<workflow id>","variables":{"order_id":"SO-100482","customer_id":"C-20931","email":"jamie.fox@example.com","currency":"NZD","lines":[{"sku":"MUG-BLK-350","qty":2,"price":24.5},{"sku":"TEE-ORG-M","qty":1,"price":39},{"sku":"BAG-CNV-01","qty":1,"price":49}],"shipping_address":{"name":"Jamie Fox","line1":"12 Example Street","city":"Wellington","postcode":"6011","country":"NZ"},"billing_country":"NZ","new_customer":false,"payment_method_ref":"pm_ref_example_4f9a21"}}'

CLI

shell
usertasks workflows inputs <workflow id>          # the start form: keys, types, required
usertasks workflows run <workflow id> --input order_id=SO-100482 --input customer_id=C-20931 --input email=jamie.fox@example.com --input currency=NZD … --wait

Inbound webhook (synchronous: the response is the workflow result)

shell
usertasks webhooks create <workflow id>          # prints the hook slug and secret once
curl -X POST "$USERTASKS_URL/api/webhooks/inbound?hook=<slug>" \
  -H "Authorization: Bearer <webhook secret>" -H "Content-Type: application/json" \
  -d '{"order_id":"SO-100482","customer_id":"C-20931","email":"jamie.fox@example.com","currency":"NZD","lines":[{"sku":"MUG-BLK-350","qty":2,"price":24.5},{"sku":"TEE-ORG-M","qty":1,"price":39},{"sku":"BAG-CNV-01","qty":1,"price":49}],"shipping_address":{"name":"Jamie Fox","line1":"12 Example Street","city":"Wellington","postcode":"6011","country":"NZ"},"billing_country":"NZ","new_customer":false,"payment_method_ref":"pm_ref_example_4f9a21"}'

What's included

12 assets, ready to adapt

TypeNameDetails
IntegrationFulfilment API
IntegrationInventory API
IntegrationPayments API
API referenceAuthorise paymentPOST /payments/authorize — Authorise (not capture) the order total against the tokenised payment method from the storefront.
API referenceCreate shipmentPOST /shipments — Create the shipment for the reserved stock, optionally on hold until a fraud review releases it.
API referenceRelease reservationPOST /reservations/{{reservation_id}}/release — Release a stock reservation when the order does not go ahead.
API referenceReserve stockPOST /reservations — Reserve stock for every order line; the reservation expires if the order is not confirmed.
API referenceUpdate shipmentPATCH /shipments/{{shipment_id}} — Release a held shipment for picking, or cancel it.
API referenceVoid authorisationPOST /payments/authorizations/{{authorization_id}}/void — Void a payment authorisation so the customer is not charged.
Decision tableFraud screening6 rules — Accept, review or reject an order from its value, shipping country, customer history and address match. First matching rule wins; NZ is the home market in the sample rules.
WorkflowManual fraud review10 steps — Runs in the background for orders the fraud rules flag for review: a reviewer releases the held shipment or cancels the order (voiding the payment authorisation and the shipment).
WorkflowOrder orchestration48 steps — Synchronous order API for a storefront: validates the order, prices it, screens it for fraud, reserves stock, authorises payment and creates the shipment, then answers the caller with the ids and delivery estimate.

Requirements

What you connect it to

Credentials never travel in a package. The install wizard asks for what your environment must provide, or installs it incomplete until you finish setup.

Needs

  • REST API — A REST API integration: set its base URL and credentials on install.
  • Inbound webhook — An inbound webhook created for the workflow, so other systems can start it.
  • Assignees — People in your workspace to receive the User Tasks (picked on install).

After installing

  1. Inventory API: set the base URL and token. Reserve stock posts to /reservations; Release reservation posts to /reservations/{id}/release.
  2. Payments API: set the base URL and token of your payment provider or payment service. Authorise payment posts to /payments/authorize with the token reference; Void authorisation posts to /payments/authorizations/{id}/void.
  3. Fulfilment API: set the base URL and token. Create shipment posts to /shipments; Update shipment patches /shipments/{id} to release or cancel a hold.
  4. Assignee: pick the fraud reviewer who handles flagged orders (the Manual fraud review sub-workflow).
  5. Edit the Fraud screening rules (home market, value thresholds) and the tax rate, shipping fee and free-shipping threshold variables.
  6. Inbound webhook: create a middleware webhook for Order orchestration and point the storefront checkout at it. Keep the steps fast; the caller waits for the response.

Asked for on install

  • Integration “Fulfilment API”Required

    • Tokenconfig.auth_config.token
    • Base urlconfig.base_urldefault https://fulfilment.example.com/api· optional

  • Integration “Inventory API”Required

    • Tokenconfig.auth_config.token
    • Base urlconfig.base_urldefault https://inventory.example.com/api· optional

  • Integration “Payments API”Required

    • Tokenconfig.auth_config.token
    • Base urlconfig.base_urldefault https://payments.example.com/v1· optional

  • Workflow “Manual fraud review” assigneesRequired

    • User for step “Review order”nodes.3.config.assignee_id

Install

Install it in your workspace

Works on UserTasks cloud and on any self-hosted instance. Installing creates the assets above; nothing runs until you complete setup and start it.

In the app

  1. Download order-orchestration-api-1.0.0.utpkg.
  2. Open Automations → Packages and drag the file onto the page (or choose Import package). Browse gallery there lists every gallery package without downloading by hand.
  3. Pick the file. The wizard verifies the checksum, every file hash and the signature, and shows the readme.
  4. Review the changes (what is created) and the data rows.
  5. Fill in the requirements, or tick Keep incomplete and finish later with Complete setup.
  6. Done: the workflow is published and active once setup is complete.

With the CLI

shell
curl -fLO https://usertasks.com/gallery/order-orchestration-api-1.0.0.utpkg
usertasks packages inspect order-orchestration-api-1.0.0.utpkg       # offline: checksum, hashes, signature
usertasks packages install order-orchestration-api-1.0.0.utpkg --dry-run
usertasks packages install order-orchestration-api-1.0.0.utpkg       # prompts for each requirement
usertasks packages install order-orchestration-api-1.0.0.utpkg --keep-incomplete --yes   # in CI; finish with:
usertasks packages complete order-orchestration-api -f values.yaml

Verify the download

File SHA-256
33e97fd79a714ba7ec4b759ad8f42ace071bbad213d75892b2a33925d5356fc7
Package checksum (what is signed)
sha256:98ca5b7a7a8c657c5c8530823f155dfbf32d42ed78ff31625e61951aa6952482
Signer
Unsigned preview build — compare the SHA-256 above

shasum -a 256 order-orchestration-api-1.0.0.utpkg should print the file SHA-256. How gallery packages are signed.

Versions

Version 1.0.0

  1. v1.0.02026-10-26First release.

Installing a newer version upgrades in place: local credentials and requirement values are kept, and changes you made are flagged first. How packages work

More packages

Related

Browse the whole gallery