RORCex API

The RORCex API is the multi-location HQ interface for RORC POS operators. It lets you author and fan-out hostcom configuration files across every store in your network, pull live and aggregated sales, inventory, and product data directly from lane systems, and run cross-store reports — all from a single authenticated service account.

Overview

• Hostcom authoring and fan-out - Author hostcom files centrally and dispatch them to any subset of your stores in a single operation, with per-target validation and a durable apply record
• Live lane data - Read sales, inventory, product, control reference, and promotion data proxied directly from individual store lanes
• HQ analytics - Aggregated dashboard metrics and cross-store reporting across your entire organization hierarchy
• Async-safe - All multi-store operations (fan-out, async reports) use a poll-based model; there are no webhooks

Hostcom Write Path

Hostcom dispatch is not a direct file push

Dispatching a hostcom batch to your stores follows a four-step workflow. The fan-out layer validates each target before any file is applied.

POST /hostcom/files/author        → author and validate the file
POST /fanout/hostcom_batch/preview → preview per-target validation (returns dispatch_id)
POST /fanout/{dispatch_id}/commit  → commit and dispatch (returns 202 + poll_url)
GET  /fanout/{dispatch_id}         → poll until terminal state

See the Async and Polling guide and Fan-out reference for full details.

Base URLs

Environment	URL
Production	https://api.rorcex.retailsuccessplatform.com/api/v1
Staging	https://api-staging.rorcex.retailsuccessplatform.com/api/v1

Authentication

All RORCex endpoints require an OAuth 2.0 Bearer token obtained from the Identity API using the Client Credentials flow. Your service account is scoped to your organization at creation time — you can only act on your own org and its descendant stores. Cross-org requests are refused with 403 Forbidden.

Most endpoints also require the X-Organization-Context header specifying the org your request acts on. For multi-store fan-out and HQ analytics, add X-Organization-Scope: CASCADE to include all descendant store orgs automatically.

See the Authentication guide for token acquisition, the full permissions table, and error reference.

Data Sources & Freshness

RORCex reads from two different places, and which one an endpoint uses determines both its freshness and how it behaves when a store is offline. Knowing the difference avoids two classes of surprise: stale numbers where you expected live ones, and 502s where you expected resilience.

The mental model

• Live lane reads hit a store's RORC back office synchronously on every request. They are as fresh as the lane itself, but they depend on that lane being reachable — if it isn't, the request returns a 502. Reach for these for operational drill-down: a specific transaction, current stock on hand, a product's configuration.
• Synced aggregate reads serve from RORCex's own database, which is continuously copied from each store's RORC back office by background pollers and reconcilers (typically within ~5 minutes). They lag slightly, but they're fast, they stay available even when a lane is down, and they answer cross-store questions a single lane can't. Reach for these for HQ dashboards and reporting.

In short, live reads trade resilience for freshness; synced reads trade freshness for resilience and cross-store reach. RORCex keeps the two paths separate by design — fanning a dashboard out to every lane in real time would make HQ reporting only as available as your least-reliable lane, and couldn't answer questions that span stores. So the platform pays a small, bounded freshness cost (the sync interval) to make multi-store reporting fast and resilient, while still offering true-live reads when you need them.

Endpoint group	Source	Freshness & availability
Sales, Inventory, Products, Promotions	RORC back office (live proxy)	Real-time; returns 502 if the lane is offline
Control Reference	RORC back office (live proxy)	Live on cache miss, otherwise served from a 24-hour cache
HQ Analytics, Reports	RORCex synced aggregate store	~5-minute lag; resilient to lane downtime; cross-store
Installs	CommerceStream + Identity (live)	Real-time agent connectivity & credential status

Two HQ exceptions: GET /hq/stores/{id}/timeseries reads the CommerceStream materialization rather than the aggregate store, and GET /hq/stores/{id}/drift is populated by the RORC two-way-interface reconciliation pipeline (empty until that pipeline is active).

Endpoint Map

Installs

Discovery and status of RORC lane installs in your network. Reflects live agent connectivity (CommerceStream) and credential status (Identity) — not a lane read.

Installs reference →

Hostcom Files

Author and validate hostcom configuration files before dispatch.

Hostcom Files reference →

Fan-out

Dispatch operations (hostcom batches, inventory adjustments) to one or more stores, with per-target validation and durable apply records.

Fan-out reference →

Hostcom Dispatches

Query and inspect the history of committed hostcom dispatches.

Hostcom Dispatches reference →

HQ Analytics

Aggregated multi-store dashboard metrics for your organization hierarchy. Served from RORCex's synced aggregate store (~5-minute lag), not live lane reads — see Data Sources & Freshness.

HQ Analytics reference →

Sales

Live sales data proxied from a single store lane.

Sales reference →

Inventory

Live inventory data proxied from a single store lane.

Inventory reference →

Products

Live product data proxied from a single store lane.

Products reference →

Promotions

Live promotion data proxied from a single store lane.

Promotions reference →

Control Reference

Control reference data proxied from a single store lane.

Control Reference reference →

Reports

Define, run, and retrieve cross-store report results. Run against the synced aggregate store, not live lane reads.

Reports reference →

Errors

Standard error envelope and status code reference.

Errors reference →

Next Steps

• Getting Started - Obtain a token and make your first call in minutes
• Authentication - OAuth setup, permissions, and token management
• Organization Scoping - Context headers, CASCADE scope, and store targeting
• Async and Polling - Fan-out and report lifecycle, polling guidance

---

Changelog

Date	Change
2026-06-11	Initial publication.