ApprovalRequest
object type
An ApprovalRequest — the real-time, human-approver, in-session authorization of ONE POS action exceeding the requester's authority (DISTINCT from the async ChangeRequest). The blocked action stays blocked until resolved; short TTL (expiresAt — a touch past it refuses CONFLICT/EXPIRED and lazily expires the request). The request binds a fingerprint (action, targetId[, valueMinor]) + the requester: on approval, RETRYING the identical gated call finds + consumes the approval by fingerprint (single-use — the marker releases in the retry's own transaction). Never self-approve (AUTHZ/SELF_APPROVAL); an under-ranked approver is AUTHZ/INSUFFICIENT.
Fields
| Field | Type | Notes |
|---|---|---|
id | ID ID! | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
sysId | String String! | The group-scoped human-facing system id (AR-…). |
type | String String! | The kind of record — always ApprovalRequest here. |
caption | String String! | The record’s display name — what people see it called. |
status | String String! | The FSM state: pending | approved | denied | expired | cancelled. |
parentId | ID ID! | deterministic parent: the open TillSession when the action runs in a till session, else the LF; rootId = the org group regardless. |
rootId | ID ID! | The org-group family root. |
createdAt | String String! | When the record was created, as a UTC timestamp. |
updatedAt | String String! | When the record last changed, as a UTC timestamp. |
revisionNum | Int Int! | How many times this record has been edited; the first save is 0. |
revision | ID ID! | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
refCaptions | RefCaption [RefCaption!]! | The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption. |
action | String String! | The gated action: discount.apply · price.override · void.line · void.transaction · return.approve · sale.restricted_item · no_sale · oversell · refund.routing_exception · credit.over_limit · order.below_minimum. Live: discount.apply · void.transaction · return.approve · no_sale · refund.routing_exception · credit.over_limit · order.below_minimum; the rest refuse VALIDATION/UNSUPPORTED naming their arrival. |
targetType | String String! | The target construct type — derived from the action, stored for the fingerprint. |
targetId | ID ID! | The blocked action's target construct. |
valueMinor | Int | The bound value (integer minor units) when the action carries one — discount.apply binds the discount Σ, EXACT-matched at consumption; absent for whole-target actions. |
requestedBy | ID ID! | The requesting User. |
requiredTier | RoleTemplateKey RoleTemplateKey! | The REQUIRED approver tier; the approver's resolved tier rank must be ≥ this tier's rank (AUTHZ/INSUFFICIENT below it). |
reason | String String! | Why the requester needs the override. |
expiresAt | String String! | The live-window end (createdAt + the 900s TTL, ISO-8601): approve/deny/consume past it refuse CONFLICT/EXPIRED and the request lazily expires. |
decidedBy | ID | DECISION-stamped: the approving/denying User (≠ requestedBy on approve — never-self-approve). |
decidedAt | String | DECISION-stamped: the decision instant (ISO-8601). |
decisionReason | String | DECISION-stamped: the approver/denier's stated reason (optional — the transition template). |