This page is for the person running a refunds back office day to day; triaging cases, deciding who approves what, and knowing when to escalate. It does not repeat the API reference; where a detail is purely technical (exact field names, GraphQL syntax, the full status enum), it links out to the page that owns that detail.

Every gap below was checked against the current docs before being written down. Where the real answer isn't published anywhere, the section says so with a FACT-NEEDED marker instead of guessing; fill those in with your Deal Engine contact and this page becomes the authoritative runbook for your team.

1. The entity model, in plain language

Four things get confused constantly: document, request, quote, and candidate. They are not four interchangeable words for "the case"; each one is a different object with a different job. The technical field-by-field version is in What is a document?, What is a quote?, What is a request?, and Document ↔ quote ↔ request. Here is the plain-language version:

How they connect: a Document is evaluated → producing a Quote → which yields a Candidate carrying a status → an agent or rule moves the Candidate to READY → processRefund submits it → the fulfillment engine executes it in the airline system and writes a terminal status (REFUNDED or ERROR) back onto the Document, along with the executed amounts (fare, tax, penalty, and total to refund; all gross figures, as plain fields on the Document). The full status table and transition rules are in Refund lifecycle & statuses.

2. The decision node (what it is, what's missing)

The high-level diagram shows four engines; Request, Validation, Calculation, Fulfillment, and a callout that Deal Engine "offers an optional decision node between the calculation engine and the fulfillment engine; to continue (or not) with the refund request." That's the only place it's mentioned. Nothing else in the docs names it, screenshots it, or explains how to operate it.

What we can confirm, from the candidate status rules:

• A candidate can be held in REVIEW; pending manual review, not yet cleared for fulfillment.
• Clients can move a candidate to READY (cleared, fulfillment will pick it up), or back to REVIEW.
• Only the fulfillment engine itself writes the terminal statuses REFUNDED or ERROR. No client action, and presumably no decision-node action, can set those directly.

So the decision node is, functionally, whatever mechanism holds a candidate in REVIEW and later moves it to READY. That much is safe to operate on.

What triggers REVIEW: a candidate lands in REVIEW when the quotation needs customer validation before it can be trusted; for example, a purged reservation or private fare rules the engine can't fully resolve on its own. Your team validates the underlying data and, once satisfied, moves the candidate from REVIEW to READY using the candidate status-update mutation. This same mechanism runs in reverse and is the kill switch: moving a candidate back to REVIEW before fulfillment picks it up pulls it out of the queue; fulfillment re-verifies that a candidate is READY immediately before executing, and only READY candidates are ever executed.

What's still missing is the rest of the mechanics of how a human actually does that day to day:

Until these are answered, treat any REVIEW queue as something you have to actively check rather than something that will page you.

3. Who can do what

The published role guide (Role & user guide) defines these roles in Onepoint:

Mapping that to the refund actions you actually need to staff:

• Moving a candidate between READY / REVIEW is performed through the candidate status-update operation. Treat the OnePoint role list as describing who is expected to do this, not as a guarantee that other roles are prevented from doing it; see the caution below.
• Overriding an amount (the fare amount to refund, which cascades to the total) is a separate UI feature (also available in OnePoint) driven by its own mutation, distinct from the status-change operation. It is not bundled with the candidate status update. The exact mutation name isn't yet confirmed publicly; ask your Deal Engine contact if you need to drive amount overrides directly via the API.
• Executing the refund is the fulfillment step. Batch ticket processing is permission-gated; confirm with Deal Engine which of your operational paths that covers before assuming a role cannot execute a refund.
• The Robot Account is a role intended for machine-to-machine API use. Its OnePoint description is read-only, but see the caution below before treating that as an enforced boundary.

🚧

Do not rely on role assignment alone as a control for money-moving actions. Which operations are permission-gated on the backend is narrower than the OnePoint permission editor implies, and the boundaries are not all published. If your controls require that a specific role cannot approve a candidate, override an amount, or execute a refund, get that confirmed in writing with Deal Engine and verify it in Sandbox for your own account, and put your own approval controls in front of the operation rather than depending solely on the role. There is no built-in maker/checker (dual-approval) control today; if your process requires a second approver before a candidate moves to READY or before an amount override is applied, you need to enforce that yourself outside the platform.

This is a derived mapping from published permissions, not a stated policy. Confirm before relying on it operationally:

4. Stuck refunds: triage table

There is no published runbook or dwell-time threshold for how long a refund can sit in a non-terminal status before it counts as "stuck." Use this table as the structure; ask Deal Engine to fill in the threshold column for your account.

Note on volume spikes: during IROPS or other volume spikes, quotations that would fall outside the synchronous SLA are automatically routed to a separate batch queue rather than hanging or failing; this protects the synchronous SLA for normal traffic. If a spike is underway, check whether an affected ticket moved to batch processing before treating it as stuck.

For the underlying status enum and what each value formally means, see Status & error reference.

5. Cancel and reverse

Before acceptance: cancelQuote(ticketNum) drops an existing quote outright. Use it any time before processRefund is called; see API usage & integration.

After execution: there is no reversal path, and this is a hard technical boundary, not a documentation gap. The refund is executed by the PSS; a third party, not by Deal Engine itself. Once a candidate reaches REFUNDED, Deal Engine has no mechanism to roll it back, offset it, or undo it from its own side. Refund lifecycle & statuses states plainly that REFUNDED is terminal and "terminal statuses never transition again"; that holds here because the money has already moved through the airline's own PSS, not merely because the API doesn't expose an "undo."

If a refund needs to be reversed, offset, or disputed after execution (a rejected application, a chargeback, or an execution error) recovery is handled through the airline's own PSS/finance processes, outside Deal Engine. Deal Engine can help you identify the affected ticket and the executed amounts, but cannot itself execute a reversal.

Before you have a live incident that needs this, confirm with your Deal Engine contact what information they need from you (ticket number, executed amounts, candidate ID) to support your airline's PSS/finance team in resolving it on their side.

6. Duplicate / already-refunded (handled outside Deal Engine)

Sometimes a refund is already processed manually in the PSS; outside Deal Engine entirely; before or instead of going through the platform. The manuallyRefunded and manualTotalAmount fields exist for exactly this: Refund amounts & reconciliation confirms that when they are present, they supersede the automated values; treat them as the source of truth.

What's not documented anywhere is how they get set:

Until that's answered, the safe operating rule is: before initiating any refund action on a ticket, check whether these fields are already populated. If they are, treat the ticket as already resolved and do not submit a duplicate processRefund.

7. Rejections: know which mode your tenant uses

Per Refund lifecycle & statuses §4.2, how a rejection surfaces is a per-customer configuration choice, not a fixed behavior:

• Default mode: the rejection is written into the refund's notes field, and the quote returns a 0 amount to be refunded. Nothing in the status itself tells you it was rejected; you have to read the note.
• Explicit mode (opt-in): a dedicated REJECTED quote status is enabled, so integrations and agents can branch on the status directly instead of reading notes and checking for a zero amount.

Your team needs to know which mode applies to you: and today there is no documented, self-serve way to check that from within the product.

Practical interim check: sandbox is documented to support simulating "rejection cases; refunds denied due to invalid data or business rules" (Testing & environments). Running a known-rejectable test ticket there and observing whether the response comes back as a REJECTED status or as notes-plus-zero will tell you which mode you're on; treat that as a workaround, not a substitute for a documented answer.

If your integration needs a machine-checkable rejection signal and you're on default mode, you can ask Deal Engine to enable the explicit REJECTED status. For the full status and decision enum, see Status & error reference.

8. Intake channels: what each one actually is

The high-level diagram shows how a refund request can enter the system. Here's what can be confirmed from elsewhere in the docs, and what's still missing per channel.

9. What to tell a passenger about timing

Keep two timelines separate when talking to a passenger: how long Deal Engine takes to process the refund request, and how long it takes for money to actually land back on their card. Only the first is something Deal Engine covers.

Processing timing (from Performance & uptime):

• Asynchronous acceptance: a few seconds to acknowledge the request; the refund keeps processing in the background.
• Synchronous quotes (Sync: true): typically 5–8 seconds, up to 25–45 seconds under PSS load, with a hard 3-minute timeout; on timeout, fall back to the webhook/async flow.
• Execution (once a candidate is submitted): can take up to roughly 2 minutes.

Settlement to the passenger is out of scope for Deal Engine; this isn't a documentation gap, it's a product boundary. Deal Engine's product covers the quotation and the refund processing together with the PSS. Once a candidate reaches REFUNDED, the funds are with the airline/PSS; the payment gateway and settlement path that gets the money back onto the passenger's original form of payment is outside the Deal Engine product, and isn't something Deal Engine can quantify for you.

The safe script: "Your refund request has been processed on our end; the funds are now with [the airline], which handles the final settlement back to your card. That step is outside our system, so we don't have a number for it, but your airline or travel agent can advise on typical timing for that final leg."

10. Escalation

For how to open or track a ticket, see Support. To escalate an existing ticket past its SLA or raise urgency, email [email protected] with [Escalation] in the subject.

The support ladder has four priority tiers (see Submitting a support ticket):

For a live money-moving incident, mark the ticket Critical and use the [Escalation] email path in parallel.

11. Case history / audit trail

Several pages reference the idea of a history without ever showing where to find it:

• Refund lifecycle & statuses says an ERROR status "carries the failure detail in its error history."
• The Quote and Request schema pages mention "audit fields" and "traceability" in the abstract (What is a quote?, Document ↔ quote ↔ request).
• The Document exposes some timestamped fields on the executed refund (requestDate, authorizationDate, updatedDate, rejectionDate) which give a partial timeline of the executed refund, but only once execution has started; they don't cover what happened while the candidate sat in NEW, REVIEW, or READY, and they aren't a general change log (who edited an amount, who moved the status, when).
• A separate webhookEvents query and UI view exist, but those record webhook delivery history (whether Deal Engine successfully notified your endpoint) not the case's own status/edit history (Webhook API reference).

None of these amounts to a documented place where an agent can see "who moved this candidate from REVIEW to READY and when" or "who changed the fare override and what it was before."

Until this is answered, if you need to reconstruct what happened on a specific ticket, your options are: pull the Document's timestamped fields for the executed portion, check webhook delivery logs for when status-change events fired, and open a support ticket with the ticket number for anything before that.