Async and Polling

RORCex has no webhooks. All asynchronous work — fan-out dispatches and long-running reports — completes in the background and exposes its progress through a polling endpoint. This page explains the lifecycle for both.

No Webhooks — Poll for Completion

When an operation returns 202 Accepted, it is running asynchronously. The response body always includes a poll_url pointing to the status resource you should check until the operation reaches a terminal state. Do not assume the work is done until you observe a terminal status in the poll response.

Fan-out Lifecycle

A fan-out operation moves through the following states.

Dispatch states

Status	Meaning
pending	The commit was accepted; the API is beginning to apply the operation to each target store
in_progress	One or more targets are still being applied
completed	All targets reached a terminal apply state and none errored
partially_failed	All targets finished, but at least one target errored
errored	The dispatch itself encountered a fatal error before any targets were reached

Per-target apply states

Apply Status	Meaning
pending	Not yet attempted for this target
applying	Currently being applied to this store lane
applied	Successfully applied
errored	Apply failed for this store; inspect the error field for details
skipped	Target was excluded (e.g., validation failure discovered after preview)

Step-by-step

1. Preview (synchronous) — Submit your operation for per-target dry-run validation. The response is synchronous and returns immediately with a dispatch_id and per-target validation_status values. Resolve any validation failures before proceeding.

curl -X POST https://api.rorcex.retailsuccessplatform.com/api/v1/fanout/hostcom_batch/preview \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{ "hostcom_file_id": "hkx_00000k1L2m3N4o5", "target_store_org_ids": ["org_00000f6G7h8I9j0"] }'

{
  "dispatch_id": "01J9XR4K7P8VN2YQ6ZB3TGD0WC",
  "targets": [
    { "store_org_id": "org_00000f6G7h8I9j0", "validation_status": "valid" }
  ]
}

2. Commit (async, returns 202) — Commit the dispatch. The API acknowledges immediately and begins applying asynchronously.

curl -X POST https://api.rorcex.retailsuccessplatform.com/api/v1/fanout/01J9XR4K7P8VN2YQ6ZB3TGD0WC/commit \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${ORG_ID}"

{
  "dispatch_id": "01J9XR4K7P8VN2YQ6ZB3TGD0WC",
  "status": "pending",
  "poll_url": "/api/v1/fanout/01J9XR4K7P8VN2YQ6ZB3TGD0WC"
}

3. Poll until terminal — Repeat the GET until every target has a terminal apply state and the top-level status is one of completed, partially_failed, or errored.

curl https://api.rorcex.retailsuccessplatform.com/api/v1/fanout/01J9XR4K7P8VN2YQ6ZB3TGD0WC \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${ORG_ID}"

{
  "dispatch_id": "01J9XR4K7P8VN2YQ6ZB3TGD0WC",
  "status": "completed",
  "targets": [
    {
      "store_org_id": "org_00000f6G7h8I9j0",
      "apply_status": "applied",
      "applied_at": "2026-06-11T14:23:07Z"
    }
  ]
}

See Fan-out reference for full request and response shapes, and the complete list of operation types.

Report Lifecycle

Reports can return inline (synchronous) or asynchronously depending on the report definition and the size of the result set.

Run a report

curl -X POST https://api.rorcex.retailsuccessplatform.com/api/v1/reports/rpt_00000a1B2c3D4e5/run \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${ORG_ID}" \
  -H "X-Organization-Scope: CASCADE" \
  -H "Content-Type: application/json" \
  -d '{ "date_from": "2026-06-01", "date_to": "2026-06-11" }'

Synchronous response (200) — The result is ready immediately and is inlined in the response body:

{
  "run_id": "01J9XS5M8Q9WP3ZR7AC4VHE1XD",
  "status": "completed",
  "result": { ... }
}

Asynchronous response (202) — The report is still running. Poll the provided URL:

{
  "run_id": "01J9XS5M8Q9WP3ZR7AC4VHE1XD",
  "status": "pending",
  "poll_url": "/api/v1/reports/runs/01J9XS5M8Q9WP3ZR7AC4VHE1XD",
  "estimated_seconds": 15
}

Poll a report run

curl https://api.rorcex.retailsuccessplatform.com/api/v1/reports/runs/01J9XS5M8Q9WP3ZR7AC4VHE1XD \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${ORG_ID}"

Report run states

Status	Meaning
pending	Queued, not yet started
running	Actively generating results
completed	Results are available
errored	Report failed; inspect the error field

Once status is completed, the result is either inlined in the poll response or available at a separate result URL indicated by the response. Report results are scoped to your organization — other orgs cannot access your run IDs.

See Reports reference for parameter shapes, result formats, and available report definitions.

Polling Guidance

• Back off gradually — Start polling a few seconds after the initial 202, then increase your interval if the operation is still running. For fan-outs across many stores, 5–10 seconds is a reasonable starting interval.
• Use poll_url — The poll_url in the commit/run response is the canonical URL for that resource. Use it directly rather than constructing the URL yourself.
• Expect in_progress transiently — Fan-out targets apply in parallel; in_progress is a normal intermediate state.
• Handle partially_failed — Inspect targets[].apply_status to identify which stores need attention. A partially_failed dispatch does not automatically retry.
• Results are durable — Completed dispatch and report run records persist and can be re-fetched at any time. You do not need to capture the result in the same poll cycle that first shows completed.

---

Changelog

Date	Change
2026-06-11	Initial publication.