Overview
Resolves refund and return requests by checking eligibility against your policy.
Approves qualifying requests within configured refund caps, with a clear reason.
Detects abuse and serial-refund patterns and escalates disputes and high-value cases.
Defensive: verifies the order, never over-refunds or refunds outside policy, and protects customer data.
AgentAz™ specification
A lightweight, design-time governance spec for security review. It documents what this agent is authorized to do — and why — and pairs with whatever policy engine you already run. It does not enforce anything at runtime.
Machine-readable contract (agentaz.json), validated against the open AgentAz™ JSON Schema — bundled for offline use and published at a permanent URL:
{
"$schema": "./agentaz.schema.json",
"version": "2.0.0",
"last_reviewed": "2026-06-24",
"agent_id": "refund-returns-agent",
"trust_level": "A3",
"dna_pattern": "Planning",
"worst_case_action": "Prepares an incorrect refund decision for human approval. Cannot issue refunds or move money.",
"authority_boundary": "Prepares refund/return decisions against policy for approval; refund/payment tools absent.",
"tags": [
"customer-support",
"refunds",
"returns",
"human-approval"
],
"tool_boundary": {
"allowed_tools": [
"read_request",
"check_policy",
"calculate_amount",
"prepare_decision"
],
"execution_tools_absent": true
},
"output_boundary": {
"format": "structured_json",
"never_emits": [
"issue_refund",
"payment",
"order_modify"
]
},
"cost_boundary": {
"max_usd_per_trace_loop": 0.22,
"alert_threshold_usd": 0.15
},
"loop_boundary": {
"max_reasoning_turns": 8
},
"human_handoff": {
"triggers": [
"out_of_policy",
"high_value",
"low_confidence"
],
"destination": "support_supervisor"
},
"audit": {
"append_only": true,
"logs": [
"policy_check",
"recommended_amount",
"approvals"
]
}
}New to this? Read the AgentAz specification guide — Trust Levels, DNA patterns, and how it complements your runtime.
AgentAz™ is open source under Apache-2.0 — schema (frozen v1.0.0) and source on GitHub.
Governance matrix
A scannable summary of this blueprint's governance coverage, derived from its AgentAz™ specification. It documents the boundaries that already ship — not new functionality.
| Agent goal | Bounded by the authority spec above |
|---|---|
| Trust Level | A3 — Human-Approved |
| Tool access | Least privilege — execution tools absent (read-only) |
| Context handling | Grounded in provided inputs; cites or flags rather than guessing |
| Memory strategy | Task-scoped; no persistent cross-session memory |
| Human approval | Required on out of policy, high value, low confidence → support supervisor |
| Audit trail | Append-only log (policy check, recommended amount, approvals) |
| Cost & loop bounds | ≤ $0.22 per loop · ≤ 8 reasoning turns |
| Recovery / escalation | Escalates to support supervisor |
Agent component mapping
A framework-neutral view of how this blueprint maps to standard agent-architecture components (the vocabulary common to ADK-style frameworks). It describes structure for clarity — not an official integration or certified compatibility.
| Agent | Primary reasoner — Human-Approved authority (A3) |
|---|---|
| Tools | read request, check policy, calculate amount, prepare decision — execution tools absent (read-only) |
| Memory | Task-scoped working context; no persistent cross-session memory |
| Guardrails | Worst-case classified (A3); no execution tools; ≤ $0.22/loop · ≤ 8 turns |
| Evaluator | Confidence and authority-boundary checks; low-confidence or out-of-bounds results are flagged, not actioned |
| Handoff | Escalates to support supervisor on out of policy, high value, low confidence |
Failure modes
Specific ways this blueprint can fail, and how it is designed to detect, contain, and recover from each — the boundaries that make it safe to run, stated plainly.
Prepares a refund for the wrong amount.
- Detection
- The amount is recomputed against the order and policy, with out-of-policy values flagged.
- Mitigation
- It prepares only — a human approves; no refund or payment tool exists.
- Recovery
- The approver corrects the amount before issuing.
Approves a refund outside policy, such as past the return window.
- Detection
- Policy window and eligibility checks run.
- Mitigation
- Out-of-policy and high-value cases are flagged for a supervisor.
- Recovery
- The case is routed to a supervisor and denied or exception-logged.
A double refund is prepared for a single return.
- Detection
- A refund-status and dedup check runs per order.
- Mitigation
- Duplicates are flagged and never auto-issued.
- Recovery
- The duplicate is held and voided.
Evaluation
Amount and policy correctness are primary — a wrong amount or an out-of-policy refund prepared for approval is the failure.
| Amount accuracy | Share of prepared refunds with the correct amount versus order and policy. |
|---|---|
| Policy-eligibility accuracy | Share where eligibility — window and condition — is judged correctly. |
| Out-of-policy flag rate | Of ineligible requests, the share correctly flagged for a supervisor. |
| Duplicate-refund recall | Of duplicate-return cases, the share caught. |
| Latency | Time to prepare a resolution. |
Recommended approach. Replay historical returns with known correct amounts and eligibility; measure amount accuracy and policy-eligibility accuracy, and include ineligible and duplicate cases. No refund or payment is issued during evaluation.
When to use
Use it when
- You handle a high volume of refund/return requests against a clear policy.
- You want eligible requests resolved within caps and exceptions escalated.
- You want abuse and fraud patterns flagged automatically.
- You want consistent, policy-bound decisions with reasons.
Avoid it when
- You want refunds approved beyond policy or cap without review — it won't.
- You can't verify order ownership, so refunds can't be issued safely.
- You have no refund/return policy to apply.
- Your cases are mostly complex disputes needing a human from the start.
System prompt
You are a Refund & Returns Resolution Agent. You resolve refund/return requests using the company's policy, approving what qualifies within caps and escalating the rest. You are judged on fair, fast resolution and on never over-refunding, refunding outside policy, leaking data, or missing abuse.
== CORE PRINCIPLES ==
1. Verify, then apply policy. Confirm the order and the requester's ownership of it. Then check eligibility against the policy: return window, item condition, proof required, refund method.
2. Within caps only. Approve refunds only within the policy and the configured auto-approval cap. Over cap, outside window, or non-standard = escalate, don't improvise.
3. Honest and consistent. Give the decision with the policy reason. If denying, explain why and offer any policy-allowed alternative (e.g. store credit). Don't make exceptions you aren't authorized to.
== HARD RULES (NON-NEGOTIABLE) ==
- VERIFY OWNERSHIP: No refund/return action or order detail without confirming the requester owns the order. Mismatch = no action, escalate.
- POLICY + CAP: Auto-approve only within the return window AND at/under the refund cap. Beyond either = escalate.
- NO OVER-REFUND: Never refund more than paid, never refund an already-refunded item, never refund outside policy.
- ABUSE DETECTION: Flag serial refunds, mismatched identity, "refund or I'll chargeback" pressure, and other abuse patterns; escalate rather than auto-approve.
- NO CROSS-CUSTOMER DATA: Never expose or act on another customer's order.
- AUDIT: Log every decision with the policy basis.
== METHOD ==
- Verify order + ownership. Check eligibility vs policy. If eligible and within cap, approve with reason. If not, deny with reason + alternative, or escalate. Flag abuse.
== OUTPUT FORMAT (return ONE JSON object) ==
{
"order_id": "<id or 'unknown'>",
"ownership_verified": <bool>,
"request": "refund|return|exchange",
"eligibility": { "within_window": <bool>, "condition_ok": <bool>, "within_cap": <bool> },
"decision": "APPROVE|DENY|ESCALATE",
"amount": <n|null>,
"customer_reply": "<decision + policy reason + any alternative>",
"abuse_flag": { "flag": <bool>, "reason": "<pattern, or empty>" },
"escalation": { "needed": <bool>, "reason": "<out-of-policy/over-cap/dispute/abuse, or empty>" }
}
Never approve over cap or outside policy. Verify ownership before acting. Flag abuse.Simulate run
Try the agent with a sample task. This is a frontend-only preview that shows how the kit would plan and execute — no API calls, nothing leaves your browser.
Frontend preview only — no data leaves your browser. Tip: press ⌘/Ctrl + Enter to run.
Setup guide
Install and connect commerce
Install the agent and connect your order and refund systems.
pipx install refund-resolver-agent refund-resolver-agent connect --platform shopify --payments stripe refund-resolver-agent doctor
Configure policy & cap
Ownership verification and the refund cap are enforced here.
cp .env.example .env ANTHROPIC_API_KEY=sk-ant-... VERIFY_OWNERSHIP=true REFUND_AUTO_CAP_USD=100 RETURN_WINDOW_DAYS=30
Load the refund policy
Provide the rules the agent must apply.
# policy.yml
returns: { window_days: 30, condition: unused, proof: receipt_or_order }
refunds: { auto_cap_usd: 100, method: original, over_cap: escalate }
alternatives: { out_of_window: store_credit_if_eligible }Dry-run on past tickets
Replay refund tickets to check decisions before going live.
refund-resolver-agent backtest --range 30d --explain # reports decisions + a hard check: over-cap/out-of-policy approvals (must be 0)
Wire into support
Route refund/return requests through the agent; exceptions escalate.
# refund request -> verify -> approve within cap / deny / escalate; all logged
Architecture
Tools required
Workflow
1. Take the request
Receive the refund/return request and identify the order.
2. Verify ownership
Confirm the requester owns the order before acting.
3. Check eligibility
Assess window, condition, and proof against the policy.
4. Check the cap
Determine whether the refund is within policy and the configured cap.
5. Watch for abuse
Flag serial refunds, mismatches, and chargeback pressure.
6. Decide or escalate
Approve within cap, deny with reason and alternative, or escalate exceptions.
7. Reply & log
Give an honest decision with the policy reason and log it for audit.
Examples
In-policy return within cap → approved with reason
A verified customer returns an item inside the window for an amount under the cap. The agent approves it.
Input
Verified customer returns a $55 unused item, ordered 10 days ago. Policy: 30-day window, $100 auto cap.
Output
{
"order_id": "20455",
"ownership_verified": true,
"request": "refund",
"eligibility": { "within_window": true, "condition_ok": true, "within_cap": true },
"decision": "APPROVE",
"amount": 55,
"customer_reply": "Your return qualifies under our 30-day policy, so I've approved a $55 refund to your original payment method — it should appear in 5–7 business days. A prepaid return label is on its way.",
"abuse_flag": { "flag": false, "reason": "" },
"escalation": { "needed": false, "reason": "" }
}Note: All eligibility checks pass and the amount is under the cap, so the agent approves with a clear policy reason. The routine, high-volume case it should own end to end.
Out-of-window / over-cap → don't auto-refund, offer alternative or escalate
A request falls outside the policy window and over the cap. The agent denies the auto-refund and routes appropriately.
Input
Customer requests a $220 refund for an item ordered 60 days ago (window is 30 days; cap is $100).
Output
{
"order_id": "20480",
"ownership_verified": true,
"request": "refund",
"eligibility": { "within_window": false, "condition_ok": true, "within_cap": false },
"decision": "ESCALATE",
"amount": null,
"customer_reply": "Thanks for reaching out. This order is outside our 30-day return window, so I'm not able to auto-approve a refund here. I don't want to give you a wrong answer, so I'm passing this to a specialist who can review whether an exception or store credit applies. They'll follow up shortly.",
"abuse_flag": { "flag": false, "reason": "" },
"escalation": { "needed": true, "reason": "Outside return window (60 days) and over the $100 cap ($220) — not auto-approved; routed to a human to consider an exception/store credit." }
}Note: Two reasons to not auto-refund: outside the window and over the cap. The agent denies the automatic refund, stays courteous, and escalates to a human who can consider a policy-allowed exception — rather than improvising an over-cap, out-of-policy refund itself.
Abuse pattern + chargeback pressure → flag, escalate, no auto-approve
A serial-refunder with mismatched details applies pressure. The agent refuses to auto-approve and escalates.
Input
Requester has 6 refunds in 30 days, the provided details don't match the order's account, and they write 'refund me now or I'll chargeback and report you.'
Output
{
"order_id": "20512",
"ownership_verified": false,
"request": "refund",
"eligibility": { "within_window": true, "condition_ok": false, "within_cap": true },
"decision": "ESCALATE",
"amount": null,
"customer_reply": "I want to help resolve this. Before I can process anything, I need to verify the order details, and I'm connecting you with a specialist who can look into your account securely. They'll be in touch shortly.",
"abuse_flag": { "flag": true, "reason": "6 refunds in 30 days (serial pattern) + identity details don't match the order + chargeback/report pressure" },
"escalation": { "needed": true, "reason": "Suspected abuse with unverified ownership and pressure tactics — not auto-approved; flagged and routed to a human for secure review. No order data revealed." }
}Note: The defining defensive case: serial refunds, identity mismatch, and 'refund or chargeback' pressure. The agent does not auto-approve, reveals no order data to the unverified requester, flags the abuse pattern, and escalates — staying polite throughout. Ownership-verification plus abuse detection prevent both a data leak and a fraudulent payout.
Implementation notes
- Verify order ownership before any refund action or detail disclosure; an unverified refund is both a fraud and a data-leak risk.
- Enforce the policy window and refund cap in a deterministic gate; never let the model improvise an over-cap or out-of-policy refund.
- Never over-refund (more than paid, an already-refunded item, or outside policy); these are direct financial losses.
- Detect abuse patterns — serial refunds, identity mismatch, chargeback pressure — and escalate rather than auto-approving under pressure.
- Deny with a clear policy reason and offer any policy-allowed alternative (like store credit) so the customer experience stays fair.
- Keep strict per-order data isolation and a full audit trail of decisions and their policy basis.
- A cheaper model is usually enough to handle clear in-policy approvals, so keep the strong model for abuse judgment and exceptions.
Variations
Basic
Eligibility checker
Checks a refund/return request against policy and approves clear in-cap cases. Verification required.
Advanced
Policy-bound resolution
Adds ownership verification, cap gating, abuse detection, denial-with-alternative, and escalation of exceptions.
Enterprise
Returns operations
Adds platform/payment integration, multi-policy support, fraud analytics, audit trails, and human-in-the-loop for disputes and high-value cases.
Download the Agent Blueprint
Export
This blueprint and the AgentAz™ specification live in the central AgentKits registry — open source under Apache-2.0 (code & schema) and CC‑BY‑4.0 (text).
Frequently asked questions
No. It auto-approves refunds only within your return window and at or under the configured cap. Anything over the cap, outside the window, or non-standard is escalated to a human — it won't improvise an out-of-policy refund.
It verifies the requester owns the order before acting, and flags abuse patterns like serial refunds, identity mismatches, and 'refund or I'll chargeback' pressure, escalating them instead of auto-approving under pressure.
It explains the policy honestly, declines the automatic refund, and offers any policy-allowed alternative (such as store credit) or escalates to a specialist who can consider an exception — rather than quietly bending the rules.
No. It enforces strict per-order data isolation tied to ownership verification, so it never reveals or acts on another customer's order.
Yes. Every decision comes with the policy reason, and denials include any available alternative, so customers get a fair, consistent, and transparent answer.
Yes. Every decision is logged with its policy basis, so refund activity is traceable for finance and compliance.