Skip to content

E-commerce — Returns Fraud Detection & Processing ​

examples/support/returns-fraud.halo policies |* parallel |! people

Automate return requests — detect fraud patterns, verify purchase history, refund low-risk returns, and send everything else to loss prevention, who approve or decline it before any money moves

Open in the playground and play with it →

halo
// ============================================================
// E-commerce — Returns Fraud Detection & Processing
// PURPOSE: Automate return requests — detect fraud patterns,
//          verify purchase history, refund low-risk returns,
//          and send everything else to loss prevention, who
//          approve or decline it before any money moves
// ============================================================

// --- Policies ---
policy PII           : Redact(CreditCard) & Redact(SSN)
// Refund abuse and wardrobing are judged by FraudDetector's score, which routes the return
// below; the policy makes sure that score is a real number from 0 to 100.
policy FraudPolicy   : Enforce(JSON) & Validate("fraud_score", ">=", "0") & Validate("fraud_score", "<=", "100")
policy CostGuard     : MaxSpend(0.50)

// --- Tools ---
tool OrdersAPI     : REST("api.shopify.com/admin/orders", apiKey: Env.SHOPIFY_KEY)
tool PaymentGW     : POST("api.stripe.com/v1/refunds", apiKey: Env.STRIPE_KEY)
tool CXSlack       : POST("hooks.slack.com/services/cx-team")

// --- Store ---
tool ReturnHistory  : VectorStore(Env.PINECONE_KEY, namespace: "return-patterns")
tool FraudSignals   : VectorStore(Env.PINECONE_KEY, namespace: "fraud-indicators")

// --- Struct ---
schema ReturnDecision {
  approved       : Boolean
  refund_amount  : Number
  fraud_score    : Number
  action         : String
}

// --- Agents ---
agent ReturnBot [openai/gpt-4o-mini, temp: 0.0]
  equips OrdersAPI, PaymentGW
  requires PII, CostGuard

agent FraudDetector [anthropic/claude-sonnet-4, temp: 0.0]
  system """
    Score how likely a return is abuse (0-100): serial returns, wardrobing
    (worn and returned), item-not-received claims against delivered orders.
    Answer JSON: {"fraud_score": <0-100>, "signals": [...]}.
  """
  equips ReturnHistory, FraudSignals
  requires PII, FraudPolicy, CostGuard

// --- The Pipeline ---
@timeout(2m)
@retry(2, 5s)
pipeline ProcessReturn(request: JSON) -> ReturnDecision:
  request
    // Step 1: Fan-out — verify order and check fraud signals in parallel
    |* {
         ReturnBot.verify_order(
           tool: OrdersAPI,
           order_id: context.data.request.order_id,
           customer_id: context.data.request.customer_id
         ),
         FraudDetector.score_risk(
           customer_id: context.data.request.customer_id,
           return_reason: context.data.request.reason,
           item_value: context.data.request.item_price,
           days_since_purchase: context.data.request.days_owned
         )
       }

    // Step 2: Route on the fraud score: a low-risk return is refunded,
    // anything else waits for loss prevention
    |? {
        (context.data.score_risk.fraud_score < 30) => Refund(context.data.request),
        else => LossPrevention(context.data.request, context.data.score_risk, context.data.verify_order),
      } as outcome

    // Step 3: Record the decision in the declared shape
    |> ReturnBot.decide(
         fraud: context.data.score_risk,
         outcome: context.data.outcome,
         request: context.data.request
       ) as decision

    // Step 4: Log the return for future pattern detection
    |> ReturnHistory.log(
         customer: context.data.request.customer_id,
         amount: context.data.request.item_price,
         reason: context.data.request.reason,
         fraud_score: context.data.score_risk.fraud_score
       )
    |> System.Value(context.data.decision)

// Issue the refund to the original payment method.
pipeline Refund(request: JSON) -> Result:
  request
    |> ReturnBot.issue_refund(
         tool: PaymentGW,
         order_id: context.data.request.order_id,
         amount: context.data.request.item_price,
         method: "original_payment"
       )

// A risky return: loss prevention approves or declines it before any money moves.
pipeline LossPrevention(request: JSON, risk: JSON, order: JSON) -> Result:
  risk
    |> CXSlack.post(
         message: "FRAUD ALERT — manual review required",
         order: context.data.order,
         fraud: context.data.risk,
         channel: "loss-prevention"
       )
    |! yield(CXSlack, context.data.risk, [context.data.order], 4h)
    ~> listen(CXSlack.Reaction) as review
    |? {
        (context.data.review.approved == true) => Refund(context.data.request),
        else => System.Value("declined by loss prevention"),
      }

curl -fsSL https://halolang.com/install.sh | sh