Control Data

The Control Data API provides cached read access to lane configuration tables for a single store. Data is sourced live from the RORC lane and cached for 24 hours. All requests require an active RORCex install for the target store.

---

Get Control Data

Retrieve a control table by kind. Results are served from a 24-hour lane-side cache. Use force_refresh=true to bypass the cache and pull fresh data directly from the lane (requires the additional control.cache.refresh permission).

GET /v1/control/{kind}

Authentication: OAuth Token (service_account or user)

Permission: rorcex:control.view (plus rorcex:control.cache.refresh when force_refresh=true)

Path Parameters

Parameter	Type	Description
kind	string	The control table to retrieve. Must be one of: terminals, cashiers, tills, media, departments, refunds, unitsofmeasure, agencies, araccounts, salesgroups, receiptgroups, zones, taxplans, settings.

Request Query Parameters

Field	Type	Required	Description
store_org_id	string	Yes	Target store organization hashkey (org_[A-Za-z0-9]{11}). Must be within the caller's org scope.
force_refresh	boolean	No	When true, bypass the 24-hour cache and fetch fresh data from the lane. Requires the rorcex:control.cache.refresh permission.

Response

{
  "store_org_id": "org_00000k1L2m3N4o5",
  "kind": "terminals",
  "cache_hit": true,
  "fetched_at": "2026-06-11T08:14:22Z",
  "data": [
    {
      "code": "01",
      "description": "LANE 1",
      "disabled": false,
      "terminalGroupCode": "01",
      "autoLogoffInterval": 0,
      "terminalAccountability": false,
      "enableCarryForward": false,
      "allowTraining": true,
      "isNativeSCO": false,
      "startAsLane": false
    }
  ]
}

Status: 200 OK

Field	Type	Description
store_org_id	string	The requested store org hashkey, echoed back.
kind	string	The control table kind, echoed from the path.
cache_hit	boolean	true if the response was served from the 24-hour cache; false if the data was fetched live (on the first request, after cache expiry, or when force_refresh=true).
fetched_at	string	ISO 8601 timestamp of when the data was last fetched from the lane. Use this to assess staleness.
data	array	Always a flat array of records for the requested kind, in camelCase. The endpoint normalizes the lane envelope, so paged kinds (e.g. cashiers) are flattened to a plain array — you never receive a nested { total, data } object. The per-kind field set varies; see Per-kind shapes.

Per-kind shapes

data is always an array of records, but each kind has its own camelCase field set. Examples:

• terminals: code, description, disabled, terminalGroupCode, autoLogoffInterval, terminalAccountability, enableCarryForward, allowTraining, isNativeSCO, startAsLane
• cashiers: code, barcodeId, firstName, lastName, displayName, disabled, trainingMode, standingLoanExempt, terminalDrawer
• media: type, subType, code, description, tenderType, electronic, sequence, enabled, loaned, pickup, pickupThreshold, returnOnAccount, allowTenderTransfer, paidIn, openCashDrawer, openTenderAllowed, fixedAmount, voidable
• settings: code, description, value, type, groupCode, groupDescription
• taxplans: code, description, terminationDate, netVendorCoupon, forgiveTaxOnVendorCouponForEbtFood, forgiveTaxOnVendorCouponForWic, disallowTaxExempt, effectives[]

⚠️ Not every lane/contract exposes every kind — on the lane used to validate these shapes, departments returned an upstream 502. Handle per-kind availability defensively.

Caching Behaviour

Control data is cached for 24 hours per store, per kind. cache_hit and fetched_at in the response indicate whether the data is fresh or stale:

• cache_hit: true — data was served from cache; fetched_at shows when it was last pulled from the lane.
• cache_hit: false — data was fetched live from the lane at the time of this request.

If you need guaranteed fresh data (e.g., after a lane configuration change), set force_refresh=true. This requires the caller to hold the rorcex:control.cache.refresh permission in addition to rorcex:control.view. Callers without control.cache.refresh that submit force_refresh=true will receive a 403 Forbidden response.

Errors

403 — Missing cache refresh permission:

{ "error": "Forbidden." }

Returned when force_refresh=true is supplied but the caller does not hold the rorcex:control.cache.refresh permission.

See Errors for authentication, authorization, upstream proxy, and store_not_found error shapes.

---

Changelog

Date	Change
2026-06-11	Initial publication.