Getting Started

This guide walks you through authenticating with the RORCex API and performing two representative tasks: reading your store network, and authoring and dispatching a hostcom file.

Prerequisites

Before you begin, ensure you have:

• An OAuth client registered with the Identity API and granted the RORCex permissions your integration needs
• Your OAuth client_id and client_secret stored securely on your backend
• The organization ID (org_…) for the org your service account is scoped to

Store credentials securely

The client_secret is only shown once at creation time. Store it in environment variables or a secrets manager — never in source control.

Step 1: Obtain an Access Token

Exchange your credentials for a Bearer token from the Identity service:

curl -X POST https://identity.retailsuccessplatform.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "scope=installs.view hostcom-batches.create hostcom-batches.dispatch fanout.execute"

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJhbGciOiJSUzI1NiIs..."
}

Cache this token and reuse it until near expiry. See Authentication for caching guidance and the full permissions table.

Step 2: List Your Installs

Verify connectivity and discover your store network by listing RORC lane installs. Pass your org ID in X-Organization-Context:

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

{
  "data": [
    {
      "install_id": "ins_00000a1B2c3D4e5",
      "store_org_id": "org_00000f6G7h8I9j0",
      "lane_count": 4,
      "status": "active",
      "version": "4.12.1"
    }
  ],
  "meta": {
    "total": 1
  }
}

Note the store_org_id values — you will use them to target individual stores for live data reads and fan-out operations.

See Installs reference for the full response shape and query parameters.

Step 3: Pull Aggregated HQ Data

Retrieve a cross-store dashboard summary for a given date. Add X-Organization-Scope: CASCADE to aggregate across all descendant store orgs:

curl "https://api.rorcex.retailsuccessplatform.com/api/v1/hq/dashboard?date=2026-06-11" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${ORG_ID}" \
  -H "X-Organization-Scope: CASCADE"

{
  "date": "2026-06-11",
  "stores_reporting": 3,
  "total_transactions": 1842,
  "total_revenue_cents": 4812650
}

See HQ Analytics reference for available metrics and date range parameters.

Step 4: Author and Fan-out a Hostcom File

Dispatching a hostcom configuration change to your stores is a four-step workflow. Each step is a separate API call.

4a. Author the file

Submit your hostcom content for server-side validation:

curl -X POST https://api.rorcex.retailsuccessplatform.com/api/v1/hostcom/files/author \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Organization-Context: ${ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "lane.cfg",
    "content": "..."
  }'

{
  "hostcom_file_id": "hkx_00000k1L2m3N4o5",
  "filename": "lane.cfg",
  "validation_status": "valid"
}

See Hostcom Files reference for the full request shape and validation error format.

4b. Preview the fan-out

Submit the authored file for a per-target dry-run. The API validates each target store and returns a dispatch_id you will use for the rest of the workflow:

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"
    }
  ]
}

If any target fails validation, resolve the issue before proceeding. See Fan-out reference for validation error shapes.

4c. Commit the dispatch

Once the preview is satisfactory, commit to apply the file across all validated targets. This returns 202 Accepted immediately; the apply happens 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"
}

4d. Poll until complete

Poll the dispatch until every target reaches a terminal apply state (applied, errored, or skipped):

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"
    }
  ]
}

Dispatch terminal statuses are completed, partially_failed, and errored. See Async and Polling for full lifecycle documentation and back-off guidance.

Next Steps

• Authentication - Permissions table, tenant binding, and token management
• Organization Scoping - Context headers, CASCADE scope, and per-store targeting
• Async and Polling - Fan-out and report lifecycle in detail
• Fan-out reference - Full request/response shapes for all operation types

---

Changelog

Date	Change
2026-06-11	Initial publication.